summaryrefslogtreecommitdiffstats
path: root/Doc/api
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2001-11-26 21:29:17 (GMT)
committerFred Drake <fdrake@acm.org>2001-11-26 21:29:17 (GMT)
commitcd8474e6a2b0baa6651f7cdefcfc9710d02c53ea (patch)
tree4763a7e6db63a61a9edfad576b8f04d042ba0ccd /Doc/api
parentccf04658b0252e91ae31a4777aef69016dc2bbb5 (diff)
downloadcpython-cd8474e6a2b0baa6651f7cdefcfc9710d02c53ea.zip
cpython-cd8474e6a2b0baa6651f7cdefcfc9710d02c53ea.tar.gz
cpython-cd8474e6a2b0baa6651f7cdefcfc9710d02c53ea.tar.bz2
Add documentation for the PyCell* APIs.
Diffstat (limited to 'Doc/api')
-rw-r--r--Doc/api/concrete.tex50
-rw-r--r--Doc/api/refcounts.dat17
2 files changed, 67 insertions, 0 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
index 64653a9..5afe6b8 100644
--- a/Doc/api/concrete.tex
+++ b/Doc/api/concrete.tex
@@ -2340,3 +2340,53 @@ information on using these objects.
Returns the description \ctype{void *} that the \ctype{PyCObject}
\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}
diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat
index 1dbbeeb..d10e909 100644
--- a/Doc/api/refcounts.dat
+++ b/Doc/api/refcounts.dat
@@ -67,6 +67,23 @@ PyCObject_FromVoidPtrAndDesc:void(*)(void*,void*):destr::
PyCObject_GetDesc:void*:::
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::
PyCallIter_New:PyObject*:sentinel::