PEP 286, Enhanced Argument Tuples, Martin von Loewis

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: