summaryrefslogtreecommitdiffstats
path: root/Doc/api/concrete.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/api/concrete.tex')
-rw-r--r--Doc/api/concrete.tex50
1 files changed, 50 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}