PEP: 286
Title: Enhanced Argument Tuples
Version: $Revision$
Last-Modified: $Date$
Author: martin@v.loewis.de (Martin von Löwis)
Status: Draft
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: