diff --git a/pep-0286.txt b/pep-0286.txt new file mode 100644 index 000000000..a396cd6bc --- /dev/null +++ b/pep-0286.txt @@ -0,0 +1,104 @@ +PEP: 286 +Title: Enhanced Argument Tuples +Version: $Revision$ +Last-Modified: $Date$ +Author: loewis@informatik.hu-berlin.de (Martin von Loewis) +Status: Active +Type: Standards Track +Created: 3-Mar-2002 +Python-Version: 2.3 +Post-History: + + +Abstract + + PyArg_ParseTuple is confronted with difficult memory management if + an argument converter creates new memory. To deal with these + cases, a specialized argument type is proposed. + + +Problem description + + Today, argument tuples keep references to the function arguments, + which are guaranteed to live as long as the argument tuple exists + which is at least as long as the function call is being executed. + + In some cases, parsing an argument will allocate new memory, which + is then to be released by the caller. This has two problems: + + 1. In case of failure, the application cannot know what memory to + release; most callers don't even know that they have the + responsibility to release that memory. Example for this are + the N converter (bug #416288) and the es# converter (bug + #501716). + + 2. Even for successful argument parsing, it is still inconvenient + for the caller to be responsible for releasing the memory. In + some cases, this is unnecessarily inefficient. For example, + the es converter copies the conversion result into memory, even + though there already is a string object that has the right + contents. + + +Proposed solution + + A new type 'argument tuple' is introduced. This type derives from + tuple, adding an __dict__ member (at tp_dictoffset -4). Instances + of this type might get the following attributes: + + - 'failobjects', a list of objects which need to be deallocated + in case of success + + - 'okobjects', a list of object which will be released when the + argument tuple is released + + To manage this type, the following functions will be added, and + used appropriately in ceval.c and getargs.c: + + - PyArgTuple_New(int); + - PyArgTuple_AddFailObject(PyObject*, PyObject*); + - PyArgTuple_AddFailMemory(PyObject*, void*); + - PyArgTuple_AddOkObject(PyObject*, PyObject*); + - PyArgTuple_AddOkMemory(PyObject*, void*); + - PyArgTuple_ClearFailed(PyObject*); + + When argument parsing fails, all fail objects will be released + through Py_DECREF, and all fail memory will be released through + PyMem_Free. If parsing succeeds, the references to the fail + objects and fail memory are dropped, without releasing anything. + + When the argument tuple is released, all ok objects and memory + will be released. + + If those functions are called with an object of a different type, + a warning is issued and no further action is taken; usage of the + affected converters without using argument tuples is deprecated. + + +Affected converters + + The following converters will add fail memory and fail objects: N, + es, et, es#, et# (unless memory is passed into the converter) + + +New converters + + To simplify Unicode conversion, the e* converters are duplicated + as E* converters (Es, Et, Es#, Et#). The usage of the E* + converters is identical to that of the e* converters, except that + the application will not need to manage the resulting memory. + This will be implemented through registration of Ok objects with + the argument tuple. The e* converters are deprecated. + + +Copyright + + This document has been placed in the public domain. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +fill-column: 70 +End: