2008-01-20 05:30:57 -04:00
|
|
|
.. highlightlang:: c
|
|
|
|
|
|
|
|
.. _supporting-cycle-detection:
|
|
|
|
|
|
|
|
Supporting Cyclic Garbage Collection
|
|
|
|
====================================
|
|
|
|
|
|
|
|
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
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
or strings), do not need to provide any explicit support for garbage
|
|
|
|
collection.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
|
2008-01-20 05:30:57 -04:00
|
|
|
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
|
2013-08-01 16:12:45 -03:00
|
|
|
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
|
|
|
|
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_GC
|
2008-01-20 07:00:14 -04:00
|
|
|
:noindex:
|
2008-01-20 05:30:57 -04:00
|
|
|
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
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.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
Constructors for container types must conform to two rules:
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
|
|
|
|
or :c:func:`PyObject_GC_NewVar`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
#. Once all the fields which may contain references to other containers are
|
2010-10-06 07:11:56 -03:00
|
|
|
initialized, it must call :c:func:`PyObject_GC_Track`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Analogous to :c:func:`PyObject_New` but for container objects with the
|
2008-01-20 05:30:57 -04:00
|
|
|
:const:`Py_TPFLAGS_HAVE_GC` flag set.
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
|
2008-01-20 05:30:57 -04:00
|
|
|
:const:`Py_TPFLAGS_HAVE_GC` flag set.
|
|
|
|
|
Merged revisions 71920-71923,71925-71929,71931-71934,71937 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71920 | jeroen.ruigrok | 2009-04-25 21:44:55 +0200 (za, 25 apr 2009) | 5 lines
Issue #4129: More documentation pointers about int -> Py_ssize_t.
Also fix up the documentation for PyObject_GC_Resize(). It seems that since
it first got documented, the documentation was actually for
_PyObject_GC_Resize().
........
r71921 | jeroen.ruigrok | 2009-04-25 21:46:19 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Documentation notes for int -> Py_ssize_t changes.
........
r71922 | jeroen.ruigrok | 2009-04-25 21:49:05 +0200 (za, 25 apr 2009) | 2 lines
Reformat, since I've been busy here anyway.
........
r71923 | jeroen.ruigrok | 2009-04-25 21:54:34 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Add a versionchanged notice for a few forgotten entries.
........
r71925 | jeroen.ruigrok | 2009-04-25 22:37:39 +0200 (za, 25 apr 2009) | 2 lines
Since it's a macro, actually refer to it as such instead of function.
........
r71926 | jeroen.ruigrok | 2009-04-25 22:40:10 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71927 | jeroen.ruigrok | 2009-04-25 22:41:40 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71928 | jeroen.ruigrok | 2009-04-25 22:43:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71929 | jeroen.ruigrok | 2009-04-25 22:44:58 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71931 | jeroen.ruigrok | 2009-04-25 22:50:27 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: int -> Py_ssize_t documentation.
........
r71932 | jeroen.ruigrok | 2009-04-25 22:55:39 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: more int -> Py_ssize_t documentation.
........
r71933 | jeroen.ruigrok | 2009-04-25 22:58:35 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: more int -> Py_ssize_t documentation.
........
r71934 | jeroen.ruigrok | 2009-04-25 23:02:34 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: field changed from int to Py_ssize_t.
........
r71937 | jeroen.ruigrok | 2009-04-25 23:16:05 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: document int -> Py_ssize_t changes.
........
2009-04-27 02:43:17 -03:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
resized object or *NULL* on failure.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyObject_GC_Track(PyObject *op)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
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
|
2013-08-01 16:12:45 -03:00
|
|
|
followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
end of the constructor.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
A macro version of :c:func:`PyObject_GC_Track`. It should not be used for
|
2008-01-20 05:30:57 -04:00
|
|
|
extension modules.
|
|
|
|
|
|
|
|
Similarly, the deallocator for the object must conform to a similar pair of
|
|
|
|
rules:
|
|
|
|
|
|
|
|
#. Before fields which refer to other containers are invalidated,
|
2010-10-06 07:11:56 -03:00
|
|
|
:c:func:`PyObject_GC_UnTrack` must be called.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyObject_GC_Del(void *op)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
|
|
|
|
:c:func:`PyObject_GC_NewVar`.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void PyObject_GC_UnTrack(void *op)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
Remove the object *op* from the set of container objects tracked by the
|
2010-10-06 07:11:56 -03:00
|
|
|
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
this object to add it back to the set of tracked objects. The deallocator
|
2013-08-01 16:12:45 -03:00
|
|
|
(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
|
|
|
|
the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for
|
2008-01-20 05:30:57 -04:00
|
|
|
extension modules.
|
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:type:: int (*visitproc)(PyObject *object, void *arg)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
The function should be called with an object to traverse as *object* and
|
2013-08-01 16:12:45 -03:00
|
|
|
the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
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.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
Traversal function for a container object. Implementations must call the
|
|
|
|
*visit* function for each object directly contained by *self*, with the
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
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.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
|
|
|
|
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
|
2008-01-20 05:30:57 -04:00
|
|
|
must name its arguments exactly *visit* and *arg*:
|
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:function:: void Py_VISIT(PyObject *o)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
|
2013-08-01 16:12:45 -03:00
|
|
|
a non-zero value, then return it. Using this macro, :c:member:`~PyTypeObject.tp_traverse`
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
handlers look like::
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
static int
|
|
|
|
my_traverse(Noddy *self, visitproc visit, void *arg)
|
|
|
|
{
|
|
|
|
Py_VISIT(self->foo);
|
|
|
|
Py_VISIT(self->bar);
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
|
2013-08-01 16:12:45 -03:00
|
|
|
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
if the object is immutable.
|
2008-01-20 05:30:57 -04:00
|
|
|
|
|
|
|
|
2010-10-06 07:11:56 -03:00
|
|
|
.. c:type:: int (*inquiry)(PyObject *self)
|
2008-01-20 05:30:57 -04:00
|
|
|
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
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
|
2010-10-06 07:11:56 -03:00
|
|
|
this method (don't just call :c:func:`Py_DECREF` on a reference). The
|
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines
The type for ppos has been Py_ssize_t since 2.5, reflect this in the
documentation.
........
r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines
Reformat paragraph.
........
r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines
Issue #4129: Belatedly document which C API functions had their argument(s) or
return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
might cause problems on 64-bit platforms.
........
r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines
Issue #4129: Document more int -> Py_ssize_t changes.
........
r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines
Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines
Since I edited this file, reformat for future edits.
........
r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to editing.
........
2009-04-26 18:06:15 -03:00
|
|
|
collector will call this method if it detects that this object is involved
|
|
|
|
in a reference cycle.
|