1 .. highlightlang:: c

     2 

     3 .. _supporting-cycle-detection:

     4 

     5 Supporting Cyclic Garbage Collection

     6 ====================================

     7 

     8 Python's support for detecting and collecting garbage which involves circular

     9 references requires support from object types which are "containers" for other

    10 objects which may also be containers.  Types which do not store references to

    11 other objects, or which only store references to atomic types (such as numbers

    12 or strings), do not need to provide any explicit support for garbage collection.

    13 

    14 .. An example showing the use of these interfaces can be found in "Supporting the

    15 .. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".

    16 

    17 To create a container type, the :attr:`tp_flags` field of the type object must

    18 include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the

    19 :attr:`tp_traverse` handler.  If instances of the type are mutable, a

    20 :attr:`tp_clear` implementation must also be provided.

    21 

    22 

    23 .. data:: Py_TPFLAGS_HAVE_GC

    24    :noindex:

    25 

    26    Objects with a type with this flag set must conform with the rules documented

    27    here.  For convenience these objects will be referred to as container objects.

    28 

    29 Constructors for container types must conform to two rules:

    30 

    31 #. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or

    32    :cfunc:`PyObject_GC_VarNew`.

    33 

    34 #. Once all the fields which may contain references to other containers are

    35    initialized, it must call :cfunc:`PyObject_GC_Track`.

    36 

    37 

    38 .. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)

    39 

    40    Analogous to :cfunc:`PyObject_New` but for container objects with the

    41    :const:`Py_TPFLAGS_HAVE_GC` flag set.

    42 

    43 

    44 .. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

    45 

    46    Analogous to :cfunc:`PyObject_NewVar` but for container objects with the

    47    :const:`Py_TPFLAGS_HAVE_GC` flag set.

    48 

    49 

    50 .. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)

    51 

    52    Resize an object allocated by :cfunc:`PyObject_NewVar`.  Returns the resized

    53    object or *NULL* on failure.

    54 

    55 

    56 .. cfunction:: void PyObject_GC_Track(PyObject *op)

    57 

    58    Adds the object *op* to the set of container objects tracked by the collector.

    59    The collector can run at unexpected times so objects must be valid while being

    60    tracked.  This should be called once all the fields followed by the

    61    :attr:`tp_traverse` handler become valid, usually near the end of the

    62    constructor.

    63 

    64 

    65 .. cfunction:: void _PyObject_GC_TRACK(PyObject *op)

    66 

    67    A macro version of :cfunc:`PyObject_GC_Track`.  It should not be used for

    68    extension modules.

    69 

    70 Similarly, the deallocator for the object must conform to a similar pair of

    71 rules:

    72 

    73 #. Before fields which refer to other containers are invalidated,

    74    :cfunc:`PyObject_GC_UnTrack` must be called.

    75 

    76 #. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.

    77 

    78 

    79 .. cfunction:: void PyObject_GC_Del(void *op)

    80 

    81    Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or

    82    :cfunc:`PyObject_GC_NewVar`.

    83 

    84 

    85 .. cfunction:: void PyObject_GC_UnTrack(void *op)

    86 

    87    Remove the object *op* from the set of container objects tracked by the

    88    collector.  Note that :cfunc:`PyObject_GC_Track` can be called again on this

    89    object to add it back to the set of tracked objects.  The deallocator

    90    (:attr:`tp_dealloc` handler) should call this for the object before any of the

    91    fields used by the :attr:`tp_traverse` handler become invalid.

    92 

    93 

    94 .. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)

    95 

    96    A macro version of :cfunc:`PyObject_GC_UnTrack`.  It should not be used for

    97    extension modules.

    98 

    99 The :attr:`tp_traverse` handler accepts a function parameter of this type:

   100 

   101 

   102 .. ctype:: int (*visitproc)(PyObject *object, void *arg)

   103 

   104    Type of the visitor function passed to the :attr:`tp_traverse` handler.  The

   105    function should be called with an object to traverse as *object* and the third

   106    parameter to the :attr:`tp_traverse` handler as *arg*.  The Python core uses

   107    several visitor functions to implement cyclic garbage detection; it's not

   108    expected that users will need to write their own visitor functions.

   109 

   110 The :attr:`tp_traverse` handler must have the following type:

   111 

   112 

   113 .. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

   114 

   115    Traversal function for a container object.  Implementations must call the

   116    *visit* function for each object directly contained by *self*, with the

   117    parameters to *visit* being the contained object and the *arg* value passed to

   118    the handler.  The *visit* function must not be called with a *NULL* object

   119    argument.  If *visit* returns a non-zero value that value should be returned

   120    immediately.

   121 

   122 To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is

   123 provided.  In order to use this macro, the :attr:`tp_traverse` implementation

   124 must name its arguments exactly *visit* and *arg*:

   125 

   126 

   127 .. cfunction:: void Py_VISIT(PyObject *o)

   128 

   129    Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a

   130    non-zero value, then return it.  Using this macro, :attr:`tp_traverse` handlers

   131    look like::

   132 

   133       static int

   134       my_traverse(Noddy *self, visitproc visit, void *arg)

   135       {

   136           Py_VISIT(self->foo);

   137           Py_VISIT(self->bar);

   138           return 0;

   139       }

   140 

   141    .. versionadded:: 2.4

   142 

   143 The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if

   144 the object is immutable.

   145 

   146 

   147 .. ctype:: int (*inquiry)(PyObject *self)

   148 

   149    Drop references that may have created reference cycles.  Immutable objects do

   150    not have to define this method since they can never directly create reference

   151    cycles.  Note that the object must still be valid after calling this method

   152    (don't just call :cfunc:`Py_DECREF` on a reference).  The collector will call

   153    this method if it detects that this object is involved in a reference cycle.