Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/cell.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 521eac31a893
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _cell-objects:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Cell Objects
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ------------
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 "Cell" objects are used to implement variables referenced by multiple scopes.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 For each such variable, a cell object is created to store the value; the local
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 variables of each stack frame that references the value contains a reference to
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 the cells from outer scopes which also use that variable. When the value is
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 accessed, the value contained in the cell is used instead of the cell object
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 itself. This de-referencing of the cell object requires support from the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 generated byte-code; these are not automatically de-referenced when accessed.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 Cell objects are not likely to be useful elsewhere.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
18 .. c:type:: PyCellObject
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 The C structure used for cell objects.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
23 .. c:var:: PyTypeObject PyCell_Type
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 The type object corresponding to cell objects.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
28 .. c:function:: int PyCell_Check(ob)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Return true if *ob* is a cell object; *ob* must not be *NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
33 .. c:function:: PyObject* PyCell_New(PyObject *ob)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 Create and return a new cell object containing the value *ob*. The parameter may
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 be *NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
39 .. c:function:: PyObject* PyCell_Get(PyObject *cell)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 Return the contents of the cell *cell*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
44 .. c:function:: PyObject* PyCell_GET(PyObject *cell)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Return the contents of the cell *cell*, but without checking that *cell* is
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 non-*NULL* and a cell object.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
50 .. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 Set the contents of the cell object *cell* to *value*. This releases the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 reference to any current content of the cell. *value* may be *NULL*. *cell*
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 success, ``0`` will be returned.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
58 .. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 Sets the value of the cell object *cell* to *value*. No reference counts are
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 be a cell object.