[Python-checkins] CVS: python/dist/src/Doc/api concrete.tex,1.1,1.2 refcounts.dat,1.36,1.37
Fred L. Drake
fdrake@users.sourceforge.net
Mon, 26 Nov 2001 13:29:20 -0800
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv5452/api
Modified Files:
concrete.tex refcounts.dat
Log Message:
Add documentation for the PyCell* APIs.
Index: concrete.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/concrete.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** concrete.tex 2001/10/12 19:01:43 1.1
--- concrete.tex 2001/11/26 21:29:17 1.2
***************
*** 2341,2342 ****
--- 2341,2392 ----
\var{self} was created with.
\end{cfuncdesc}
+
+
+ \subsection{Cell Objects \label{cell-objects}}
+
+ ``Cell'' objects are used to implement variables referenced by
+ multiple scopes. For each such variable, a cell object is created to
+ store the value; the local variables of each stack frame that
+ references the value contains a reference to the cells from outer
+ scopes which also use that variable. When the value is accessed, the
+ value contained in the cell is used instead of the cell object
+ itself. This de-referencing of the cell object requires support from
+ the generated byte-code; these are not automatically de-referenced
+ when accessed. Cell objects are not likely to be useful elsewhere.
+
+ \begin{cvardesc}{PyTypeObject}{PyCell_Type}
+ The type object corresponding to cell objects
+ \end{cvardesc}
+
+ \begin{cfuncdesc}{int}{PyCell_Check}{ob}
+ Return true if \var{ob} is a cell object; \var{ob} must not be
+ \NULL.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
+ Create and return a new cell object containing the value \var{ob}.
+ The parameter may be \NULL.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
+ Return the contents of the cell \var{cell}.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell}
+ Return the contents of the cell \var{cell}, but without checking
+ that \var{cell} is non-\NULL{} and a call object.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
+ Set the contents of the cell object \var{cell} to \var{value}. This
+ releases the reference to any current content of the cell.
+ \var{value} may be \NULL. \var{cell} must be non-\NULL; if it is
+ not a cell object, \code{-1} will be returned. On success, \code{0}
+ will be returned.
+ \end{cfuncdesc}
+
+ \begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value}
+ Sets the value of the cell object \var{cell} to \var{value}. No
+ reference counts are adjusted, and no checks are made for safety;
+ \var{cell} must be non-\NULL{} and must be a cell object.
+ \end{cfuncdesc}
Index: refcounts.dat
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/refcounts.dat,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -d -r1.36 -r1.37
*** refcounts.dat 2001/10/29 17:43:14 1.36
--- refcounts.dat 2001/11/26 21:29:17 1.37
***************
*** 68,71 ****
--- 68,88 ----
PyCObject_GetDesc:PyObject*:self:0:
+ PyCell_New:PyObject*::+1:
+ PyCell_New:PyObject*:ob:0:
+
+ PyCell_GET:PyObject*::0:
+ PyCell_GET:PyObject*:ob:0:
+
+ PyCell_Get:PyObject*::+1:
+ PyCell_Get:PyObject*:cell:0:
+
+ PyCell_SET:void:::
+ PyCell_SET:PyObject*:cell:0:
+ PyCell_SET:PyObject*:value:0:
+
+ PyCell_Set:int:::
+ PyCell_Set:PyObject*:cell:0:
+ PyCell_Set:PyObject*:value:0:
+
PyCallIter_New:PyObject*::+1:
PyCallIter_New:PyObject*:callable::