Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/cell.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 13dc65fe8599
children 521eac31a893
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _cell-objects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Cell Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 "Cell" objects are used to implement variables referenced by multiple scopes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 For each such variable, a cell object is created to store the value; the local
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 variables of each stack frame that references the value contains a reference to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 the cells from outer scopes which also use that variable. When the value is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 accessed, the value contained in the cell is used instead of the cell object
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 itself. This de-referencing of the cell object requires support from the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 generated byte-code; these are not automatically de-referenced when accessed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 Cell objects are not likely to be useful elsewhere.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 .. ctype:: PyCellObject
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 The C structure used for cell objects.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 .. cvar:: PyTypeObject PyCell_Type
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 The type object corresponding to cell objects.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 .. cfunction:: int PyCell_Check(ob)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Return true if *ob* is a cell object; *ob* must not be *NULL*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 .. cfunction:: PyObject* PyCell_New(PyObject *ob)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 Create and return a new cell object containing the value *ob*. The parameter may
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 be *NULL*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 .. cfunction:: PyObject* PyCell_Get(PyObject *cell)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 Return the contents of the cell *cell*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 .. cfunction:: PyObject* PyCell_GET(PyObject *cell)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Return the contents of the cell *cell*, but without checking that *cell* is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 non-*NULL* and a cell object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 Set the contents of the cell object *cell* to *value*. This releases the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 reference to any current content of the cell. *value* may be *NULL*. *cell*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 success, ``0`` will be returned.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 .. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 Sets the value of the cell object *cell* to *value*. No reference counts are
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 be a cell object.