[Python-checkins] CVS: python/dist/src/Doc/api concrete.tex,1.1,1.2 refcounts.dat,1.36,1.37

[Fred L. Drake]

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::