[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.142,1.143
Neil Schemenauer
nascheme@users.sourceforge.net
Thu, 30 Aug 2001 08:24:19 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv3569/Doc/api
Modified Files:
api.tex
Log Message:
Update documentation for GC API. Closes SF patch #421893.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.142
retrieving revision 1.143
diff -C2 -d -r1.142 -r1.143
*** api.tex 2001/08/28 02:31:28 1.142
--- api.tex 2001/08/30 15:24:17 1.143
***************
*** 5509,5519 ****
To create a container type, the \member{tp_flags} field of the type
! object must include the \constant{Py_TPFLAGS_GC} and provide an
! implementation of the \member{tp_traverse} handler. The computed
! value of the \member{tp_basicsize} field must include
! \constant{PyGC_HEAD_SIZE} as well. If instances of the type are
! mutable, a \member{tp_clear} implementation must also be provided.
! \begin{datadesc}{Py_TPFLAGS_GC}
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to
--- 5509,5518 ----
To create a container type, the \member{tp_flags} field of the type
! object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
! implementation of the \member{tp_traverse} handler. If instances of the
! type are mutable, a \member{tp_clear} implementation must also be
! provided.
! \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to
***************
*** 5521,5542 ****
\end{datadesc}
- \begin{datadesc}{PyGC_HEAD_SIZE}
- Extra memory needed for the garbage collector. Container objects
- must include this in the calculation of their tp_basicsize. If the
- collector is disabled at compile time then this is \code{0}.
- \end{datadesc}
-
Constructors for container types must conform to two rules:
\begin{enumerate}
\item The memory for the object must be allocated using
! \cfunction{PyObject_New()} or \cfunction{PyObject_VarNew()}.
\item Once all the fields which may contain references to other
containers are initialized, it must call
! \cfunction{PyObject_GC_Init()}.
\end{enumerate}
! \begin{cfuncdesc}{void}{PyObject_GC_Init}{PyObject *op}
Adds the object \var{op} to the set of container objects tracked by
the collector. The collector can run at unexpected times so objects
--- 5520,5551 ----
\end{datadesc}
Constructors for container types must conform to two rules:
\begin{enumerate}
\item The memory for the object must be allocated using
! \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
\item Once all the fields which may contain references to other
containers are initialized, it must call
! \cfunction{PyObject_GC_Track()}.
\end{enumerate}
! \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
! Analogous to \cfunction{PyObject_New()} but for container objects with
! the \constant{Py_TPFLAGS_HAVE_GC} flag set.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
! int size}
! Analogous to \cfunction{PyObject_NewVar()} but for container objects
! with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
! Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
! the resized object or \NULL{} on failure.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
Adds the object \var{op} to the set of container objects tracked by
the collector. The collector can run at unexpected times so objects
***************
*** 5546,5549 ****
--- 5555,5563 ----
\end{cfuncdesc}
+ \begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
+ A macro version of \cfunction{PyObject_GC_Track()}. It should not be
+ used for extension modules.
+ \end{cfuncdesc}
+
Similarly, the deallocator for the object must conform to a similar
pair of rules:
***************
*** 5551,5572 ****
\begin{enumerate}
\item Before fields which refer to other containers are invalidated,
! \cfunction{PyObject_GC_Fini()} must be called.
\item The object's memory must be deallocated using
! \cfunction{PyObject_Del()}.
\end{enumerate}
! \begin{cfuncdesc}{void}{PyObject_GC_Fini}{PyObject *op}
Remove the object \var{op} from the set of container objects tracked
! by the collector. Note that \cfunction{PyObject_GC_Init()} can be
called again on this object to add it back to the set of tracked
objects. The deallocator (\member{tp_dealloc} handler) should call
this for the object before any of the fields used by the
\member{tp_traverse} handler become invalid.
! \strong{Note:} Any container which may be referenced from another
! object reachable by the collector must itself be tracked by the
! collector, so it is generally not safe to call this function
! anywhere but in the object's deallocator.
\end{cfuncdesc}
--- 5565,5591 ----
\begin{enumerate}
\item Before fields which refer to other containers are invalidated,
! \cfunction{PyObject_GC_UnTrack()} must be called.
\item The object's memory must be deallocated using
! \cfunction{PyObject_GC_Del()}.
\end{enumerate}
! \begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
! Releases memory allocated to an object using
! \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
Remove the object \var{op} from the set of container objects tracked
! by the collector. Note that \cfunction{PyObject_GC_Track()} can be
called again on this object to add it back to the set of tracked
objects. The deallocator (\member{tp_dealloc} handler) should call
this for the object before any of the fields used by the
\member{tp_traverse} handler become invalid.
+ \end{cfuncdesc}
! \begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
! A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be
! used for extension modules.
\end{cfuncdesc}
***************
*** 5651,5657 ****
my_dealloc(MyObject *self)
{
! PyObject_GC_Fini((PyObject *) self);
Py_XDECREF(self->container);
! PyObject_Del(self);
}
\end{verbatim}
--- 5670,5676 ----
my_dealloc(MyObject *self)
{
! PyObject_GC_UnTrack((PyObject *) self);
Py_XDECREF(self->container);
! PyObject_GC_Del(self);
}
\end{verbatim}
***************
*** 5663,5667 ****
0,
"MyObject",
! sizeof(MyObject) + PyGC_HEAD_SIZE,
0,
(destructor)my_dealloc, /* tp_dealloc */
--- 5682,5686 ----
0,
"MyObject",
! sizeof(MyObject),
0,
(destructor)my_dealloc, /* tp_dealloc */
***************
*** 5680,5684 ****
0, /* tp_setattro */
0, /* tp_as_buffer */
! Py_TPFLAGS_DEFAULT | Py_TPFLAGS_GC,
0, /* tp_doc */
(traverseproc)my_traverse, /* tp_traverse */
--- 5699,5703 ----
0, /* tp_setattro */
0, /* tp_as_buffer */
! Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
0, /* tp_doc */
(traverseproc)my_traverse, /* tp_traverse */
***************
*** 5696,5703 ****
if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
! result = PyObject_New(MyObject, &MyObject_Type);
if (result != NULL) {
result->container = container;
! PyObject_GC_Init();
}
}
--- 5715,5722 ----
if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
! result = PyObject_GC_New(MyObject, &MyObject_Type);
if (result != NULL) {
result->container = container;
! PyObject_GC_Track(result);
}
}