From cd8474e6a2b0baa6651f7cdefcfc9710d02c53ea Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Mon, 26 Nov 2001 21:29:17 +0000
Subject: Add documentation for the PyCell* APIs.

---
 Doc/api/concrete.tex  | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Doc/api/refcounts.dat | 17 +++++++++++++++++
 2 files changed, 67 insertions(+)

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::
-- 
cgit v0.12