[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.109,1.110

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv28897/api

Modified Files:
	api.tex 
Log Message:

Integrated an expanded version of some text from Neil Schemenauer about
supporting cyclic garbage collection.  (This is not all of it, but I'm
taking a break!)

Also fixed some markup nits.


Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.109
retrieving revision 1.110
diff -C2 -r1.109 -r1.110
*** api.tex	2001/03/16 15:41:29	1.109
--- api.tex	2001/03/21 22:15:01	1.110
***************
*** 4870,4875 ****
  
  \strong{Note:} It is very important that your
! \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
! value of the \member{tp_flags} member rather than \code{0}.  This
  tells the Python runtime that your \ctype{PyBufferProcs} structure
  contains the \member{bf_getcharbuffer} slot. Older versions of Python
--- 4870,4875 ----
  
  \strong{Note:} It is very important that your
! \ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for
! the value of the \member{tp_flags} member rather than \code{0}.  This
  tells the Python runtime that your \ctype{PyBufferProcs} structure
  contains the \member{bf_getcharbuffer} slot. Older versions of Python
***************
*** 4899,4903 ****
  The last slot is \member{bf_getcharbuffer}, of type
  \ctype{getcharbufferproc}.  This slot will only be present if the
! \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
  \member{tp_flags} field of the object's \ctype{PyTypeObject}.  Before using
  this slot, the caller should test whether it is present by using the
--- 4899,4903 ----
  The last slot is \member{bf_getcharbuffer}, of type
  \ctype{getcharbufferproc}.  This slot will only be present if the
! \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
  \member{tp_flags} field of the object's \ctype{PyTypeObject}.  Before using
  this slot, the caller should test whether it is present by using the
***************
*** 4961,4964 ****
--- 4961,5046 ----
  \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
                              (PyObject *self, int segment, const char **ptrptr)}
+ \end{ctypedesc}
+ 
+ 
+ \section{Supporting Cyclic Garbarge Collection
+          \label{supporting-cycle-detection}}
+ 
+ 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.
+ 
+ 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 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
+   as container objects.
+ \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}
+ 
+ \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
+   must be valid while being tracked.  This should be called once all
+   the fields followed by the \member{tp_traverse} handler become valid,
+   usually near the end of the constructor.
+ \end{cfuncdesc}
+ 
+ \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.
+ \end{cfuncdesc}
+ 
+ The \member{tp_traverse} handler accepts a function parameter of this
+ type:
+ 
+ \begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
+   Type of the visitor function passed to the \member{tp_traverse}
+   handler.  The function should be called with an object to traverse
+   as \var{object} and the third parameter to the \member{tp_traverse}
+   handler as \var{arg}.
+ \end{ctypedesc}
+ 
+ The \member{tp_traverse} handler must have the following type:
+ 
+ \begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
+                                 visitproc visit, void *arg)}
+   Traversal function for a container object.  Implementations must
+   call the \var{visit} function for each object directly contained by
+   \var{self}, with the parameters to \var{visit} being the contained
+   object and the \var{arg} value passed to the handler.  If
+   \var{visit} returns a non-zero value then an error has occurred and
+   that value should be returned immediately.
+ \end{ctypedesc}
+ 
+ The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
+ \NULL{} if the object is immutable.
+ 
+ \begin{ctypedesc}[inquiry]{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 (i.e., don't just call
+   \cfunction{Py_DECREF()} on a reference).  The collector will call
+   this method if it detects that this object is involved in a
+   reference cycle.
  \end{ctypedesc}