Reformat prior to editing.
This commit is contained in:
Jeroen Ruigrok van der Werven
parent
1ae8c88030
commit
3537124058
|
|
@ -9,7 +9,8 @@ Python's support for detecting and collecting garbage which involves circular
|
|||
references requires support from object types which are "containers" for other
|
||||
objects which may also be containers. Types which do not store references to
|
||||
other objects, or which only store references to atomic types (such as numbers
|
||||
or strings), do not need to provide any explicit support for garbage collection.
|
||||
or strings), do not need to provide any explicit support for garbage
|
||||
collection.
|
||||
|
||||
.. An example showing the use of these interfaces can be found in "Supporting the
|
||||
.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
|
||||
|
|
@ -23,13 +24,14 @@ include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
|
|||
.. data:: Py_TPFLAGS_HAVE_GC
|
||||
:noindex:
|
||||
|
||||
Objects with a type with this flag set must conform with the rules documented
|
||||
here. For convenience these objects will be referred to as container objects.
|
||||
Objects with a type with this flag set must conform with the rules
|
||||
documented here. For convenience these objects will be referred to as
|
||||
container objects.
|
||||
|
||||
Constructors for container types must conform to two rules:
|
||||
|
||||
#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or
|
||||
:cfunc:`PyObject_GC_VarNew`.
|
||||
#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
|
||||
or :cfunc:`PyObject_GC_VarNew`.
|
||||
|
||||
#. Once all the fields which may contain references to other containers are
|
||||
initialized, it must call :cfunc:`PyObject_GC_Track`.
|
||||
|
|
@ -49,17 +51,17 @@ Constructors for container types must conform to two rules:
|
|||
|
||||
.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
|
||||
|
||||
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized
|
||||
object or *NULL* on failure.
|
||||
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
|
||||
resized object or *NULL* on failure.
|
||||
|
||||
|
||||
.. cfunction:: void PyObject_GC_Track(PyObject *op)
|
||||
|
||||
Adds the object *op* to the set of container objects tracked by the collector.
|
||||
The collector can run at unexpected times so objects must be valid while being
|
||||
tracked. This should be called once all the fields followed by the
|
||||
:attr:`tp_traverse` handler become valid, usually near the end of the
|
||||
constructor.
|
||||
Adds the object *op* to the set of container objects tracked by the
|
||||
collector. The collector can run at unexpected times so objects must be
|
||||
valid while being tracked. This should be called once all the fields
|
||||
followed by the :attr:`tp_traverse` handler become valid, usually near the
|
||||
end of the constructor.
|
||||
|
||||
|
||||
.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
|
||||
|
|
@ -85,10 +87,10 @@ rules:
|
|||
.. cfunction:: void PyObject_GC_UnTrack(void *op)
|
||||
|
||||
Remove the object *op* from the set of container objects tracked by the
|
||||
collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this
|
||||
object to add it back to the set of tracked objects. The deallocator
|
||||
(:attr:`tp_dealloc` handler) should call this for the object before any of the
|
||||
fields used by the :attr:`tp_traverse` handler become invalid.
|
||||
collector. Note that :cfunc:`PyObject_GC_Track` can be called again on
|
||||
this object to add it back to the set of tracked objects. The deallocator
|
||||
(:attr:`tp_dealloc` handler) should call this for the object before any of
|
||||
the fields used by the :attr:`tp_traverse` handler become invalid.
|
||||
|
||||
|
||||
.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
|
||||
|
|
@ -101,11 +103,12 @@ The :attr:`tp_traverse` handler accepts a function parameter of this type:
|
|||
|
||||
.. ctype:: int (*visitproc)(PyObject *object, void *arg)
|
||||
|
||||
Type of the visitor function passed to the :attr:`tp_traverse` handler. The
|
||||
function should be called with an object to traverse as *object* and the third
|
||||
parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses
|
||||
several visitor functions to implement cyclic garbage detection; it's not
|
||||
expected that users will need to write their own visitor functions.
|
||||
Type of the visitor function passed to the :attr:`tp_traverse` handler.
|
||||
The function should be called with an object to traverse as *object* and
|
||||
the third parameter to the :attr:`tp_traverse` handler as *arg*. The
|
||||
Python core uses several visitor functions to implement cyclic garbage
|
||||
detection; it's not expected that users will need to write their own
|
||||
visitor functions.
|
||||
|
||||
The :attr:`tp_traverse` handler must have the following type:
|
||||
|
||||
|
|
@ -114,10 +117,10 @@ The :attr:`tp_traverse` handler must have the following type:
|
|||
|
||||
Traversal function for a container object. Implementations must call the
|
||||
*visit* function for each object directly contained by *self*, with the
|
||||
parameters to *visit* being the contained object and the *arg* value passed to
|
||||
the handler. The *visit* function must not be called with a *NULL* object
|
||||
argument. If *visit* returns a non-zero value that value should be returned
|
||||
immediately.
|
||||
parameters to *visit* being the contained object and the *arg* value passed
|
||||
to the handler. The *visit* function must not be called with a *NULL*
|
||||
object argument. If *visit* returns a non-zero value that value should be
|
||||
returned immediately.
|
||||
|
||||
To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
|
||||
provided. In order to use this macro, the :attr:`tp_traverse` implementation
|
||||
|
|
@ -126,9 +129,9 @@ must name its arguments exactly *visit* and *arg*:
|
|||
|
||||
.. cfunction:: void Py_VISIT(PyObject *o)
|
||||
|
||||
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
|
||||
non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers
|
||||
look like::
|
||||
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
|
||||
a non-zero value, then return it. Using this macro, :attr:`tp_traverse`
|
||||
handlers look like::
|
||||
|
||||
static int
|
||||
my_traverse(Noddy *self, visitproc visit, void *arg)
|
||||
|
|
@ -140,14 +143,15 @@ must name its arguments exactly *visit* and *arg*:
|
|||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
|
||||
the object is immutable.
|
||||
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
|
||||
if the object is immutable.
|
||||
|
||||
|
||||
.. ctype:: int (*inquiry)(PyObject *self)
|
||||
|
||||
Drop references that may have created reference cycles. Immutable objects do
|
||||
not have to define this method since they can never directly create reference
|
||||
cycles. Note that the object must still be valid after calling this method
|
||||
(don't just call :cfunc:`Py_DECREF` on a reference). The collector will call
|
||||
this method if it detects that this object is involved in a reference cycle.
|
||||
Drop references that may have created reference cycles. Immutable objects
|
||||
do not have to define this method since they can never directly create
|
||||
reference cycles. Note that the object must still be valid after calling
|
||||
this method (don't just call :cfunc:`Py_DECREF` on a reference). The
|
||||
collector will call this method if it detects that this object is involved
|
||||
in a reference cycle.
|
||||
|
|
|
|||
Loading…
Reference in New Issue