Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/allocation.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 6255a72a4c1e
children b36cb4602e21
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 .. _allocating-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 Allocating Objects on the Heap
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
14 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
15 This function used an :ctype:`int` type for *size*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
16 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
17
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 .. cfunction:: void _PyObject_Del(PyObject *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
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 .. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
24 Initialize a newly-allocated object *op* with its type and initial
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
25 reference. Returns the initialized object. If *type* indicates that the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
26 object participates in the cyclic garbage detector, it is added to the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
27 detector's set of observed objects. Other fields of the object are not
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
28 affected.
44796
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 .. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
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 This does everything :cfunc:`PyObject_Init` does, and also initializes the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 length information for a variable-size object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
53425
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
36 .. versionchanged:: 2.5
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
37 This function used an :ctype:`int` type for *size*. This might require
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
38 changes in your code for properly supporting 64-bit systems.
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
39
44796
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 .. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
43 Allocate a new Python object using the C structure type *TYPE* and the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
44 Python type object *type*. Fields not defined by the Python object header
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
45 are not initialized; the object's reference count will be one. The size of
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
46 the memory allocation is determined from the :attr:`tp_basicsize` field of
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
47 the type object.
44796
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:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
52 Allocate a new Python object using the C structure type *TYPE* and the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
53 Python type object *type*. Fields not defined by the Python object header
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
54 are not initialized. The allocated memory allows for the *TYPE* structure
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
55 plus *size* fields of the size given by the :attr:`tp_itemsize` field of
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
56 *type*. This is useful for implementing objects like tuples, which are
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
57 able to determine their size at construction time. Embedding the array of
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
58 fields into the same allocation decreases the number of allocations,
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
59 improving the memory management efficiency.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
53425
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
61 .. versionchanged:: 2.5
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
62 This function used an :ctype:`int` type for *size*. This might require
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
63 changes in your code for properly supporting 64-bit systems.
6255a72a4c1e Issue #4129: Documentation notes for int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53420
diff changeset
64
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 .. cfunction:: void PyObject_Del(PyObject *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 Releases memory allocated to an object using :cfunc:`PyObject_New` or
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
69 :cfunc:`PyObject_NewVar`. This is normally called from the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
70 :attr:`tp_dealloc` handler specified in the object's type. The fields of
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
71 the object should not be accessed after this call as the memory is no
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
72 longer a valid Python object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 .. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
77 Create a new module object based on a name and table of functions,
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
78 returning the new module object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 .. versionchanged:: 2.3
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
81 Older versions of Python did not support *NULL* as the value for the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
82 *methods* argument.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 .. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
87 Create a new module object based on a name and table of functions,
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
88 returning the new module object. If *doc* is non-*NULL*, it will be used
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
89 to define the docstring for the module.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 .. versionchanged:: 2.3
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
92 Older versions of Python did not support *NULL* as the value for the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
93 *methods* argument.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 .. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
98 Create a new module object based on a name and table of functions,
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
99 returning the new module object. If *doc* is non-*NULL*, it will be used
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
100 to define the docstring for the module. If *self* is non-*NULL*, it will
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
101 passed to the functions of the module as their (otherwise *NULL*) first
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
102 parameter. (This was added as an experimental feature, and there are no
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
103 known uses in the current version of Python.) For *apiver*, the only value
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
104 which should be passed is defined by the constant
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
105 :const:`PYTHON_API_VERSION`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
109 Most uses of this function should probably be using the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
110 :cfunc:`Py_InitModule3` instead; only use this if you are sure you need
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
111 it.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 .. versionchanged:: 2.3
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
114 Older versions of Python did not support *NULL* as the value for the
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
115 *methods* argument.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. cvar:: PyObject _Py_NoneStruct
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
53420
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
120 Object which is visible in Python as ``None``. This should only be
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
121 accessed using the ``Py_None`` macro, which evaluates to a pointer to this
f88306c8265e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
122 object.