Debian Codegraph @

Doc/c-api/allocation.rst

raw
1 .. highlight:: c
2
3 .. _allocating-objects:
4
5 Allocating objects on the heap
6 ==============================
7
8
9 .. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
10
11
12 .. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
13
14
15 .. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
16
17 Initialize a newly allocated object *op* with its type and initial
18 reference. Returns the initialized object. Other fields of the object are
19 not initialized. Despite its name, this function is unrelated to the
20 object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
21 slot). Specifically, this function does **not** call the object's
22 :meth:`!__init__` method.
23
24 In general, consider this function to be a low-level routine. Use
25 :c:member:`~PyTypeObject.tp_alloc` where possible.
26 For implementing :c:member:`!tp_alloc` for your type, prefer
27 :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.
28
29 .. note::
30
31 This function only initializes the object's memory corresponding to the
32 initial :c:type:`PyObject` structure. It does not zero the rest.
33
34
35 .. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
36
37 This does everything :c:func:`PyObject_Init` does, and also initializes the
38 length information for a variable-size object.
39
40 .. note::
41
42 This function only initializes some of the object's memory. It does not
43 zero the rest.
44
45
46 .. c:macro:: PyObject_New(TYPE, typeobj)
47
48 Allocates a new Python object using the C structure type *TYPE* and the
49 Python type object *typeobj* (``PyTypeObject*``) by calling
50 :c:func:`PyObject_Malloc` to allocate memory and initializing it like
51 :c:func:`PyObject_Init`. The caller will own the only reference to the
52 object (i.e. its reference count will be one).
53
54 Avoid calling this directly to allocate memory for an object; call the type's
55 :c:member:`~PyTypeObject.tp_alloc` slot instead.
56
57 When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
58 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
59 simply calls this macro.
60
61 This macro does not call :c:member:`~PyTypeObject.tp_alloc`,
62 :c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
63 :c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).
64
65 This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
66 :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.
67
68 Memory allocated by this macro must be freed with :c:func:`PyObject_Free`
69 (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
70
71 .. note::
72
73 The returned memory is not guaranteed to have been completely zeroed
74 before it was initialized.
75
76 .. note::
77
78 This macro does not construct a fully initialized object of the given
79 type; it merely allocates memory and prepares it for further
80 initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
81 fully initialized object, call *typeobj* instead. For example::
82
83 PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
84
85 .. seealso::
86
87 * :c:func:`PyObject_Free`
88 * :c:macro:`PyObject_GC_New`
89 * :c:func:`PyType_GenericAlloc`
90 * :c:member:`~PyTypeObject.tp_alloc`
91
92
93 .. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
94
95 Like :c:macro:`PyObject_New` except:
96
97 * It allocates enough memory for the *TYPE* structure plus *size*
98 (``Py_ssize_t``) fields of the size given by the
99 :c:member:`~PyTypeObject.tp_itemsize` field of *typeobj*.
100 * The memory is initialized like :c:func:`PyObject_InitVar`.
101
102 This is useful for implementing objects like tuples, which are able to
103 determine their size at construction time. Embedding the array of fields
104 into the same allocation decreases the number of allocations, improving the
105 memory management efficiency.
106
107 Avoid calling this directly to allocate memory for an object; call the type's
108 :c:member:`~PyTypeObject.tp_alloc` slot instead.
109
110 When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
111 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
112 simply calls this macro.
113
114 This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
115 :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar`
116 instead.
117
118 Memory allocated by this function must be freed with :c:func:`PyObject_Free`
119 (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
120
121 .. note::
122
123 The returned memory is not guaranteed to have been completely zeroed
124 before it was initialized.
125
126 .. note::
127
128 This macro does not construct a fully initialized object of the given
129 type; it merely allocates memory and prepares it for further
130 initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
131 fully initialized object, call *typeobj* instead. For example::
132
133 PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
134
135 .. seealso::
136
137 * :c:func:`PyObject_Free`
138 * :c:macro:`PyObject_GC_NewVar`
139 * :c:func:`PyType_GenericAlloc`
140 * :c:member:`~PyTypeObject.tp_alloc`
141
142
143 .. c:var:: PyObject _Py_NoneStruct
144
145 Object which is visible in Python as ``None``. This should only be accessed
146 using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
147 object.
148
149
150 .. seealso::
151
152 :ref:`moduleobjects`
153 To allocate and create extension modules.
154
155
156 Soft-deprecated aliases
157 ^^^^^^^^^^^^^^^^^^^^^^^
158
159 .. soft-deprecated:: 3.10
160
161 These are aliases to existing functions and macros.
162 They exist solely for backwards compatibility.
163
164
165 .. list-table::
166 :widths: auto
167 :header-rows: 1
168
169 * * Soft-deprecated alias
170 * Function
171 * * .. c:macro:: PyObject_NEW(type, typeobj)
172 * :c:macro:`PyObject_New`
173 * * .. c:macro:: PyObject_NEW_VAR(type, typeobj, n)
174 * :c:macro:`PyObject_NewVar`
175 * * .. c:macro:: PyObject_INIT(op, typeobj)
176 * :c:func:`PyObject_Init`
177 * * .. c:macro:: PyObject_INIT_VAR(op, typeobj, n)
178 * :c:func:`PyObject_InitVar`
179 * * .. c:macro:: PyObject_MALLOC(n)
180 * :c:func:`PyObject_Malloc`
181 * * .. c:macro:: PyObject_REALLOC(p, n)
182 * :c:func:`PyObject_Realloc`
183 * * .. c:macro:: PyObject_FREE(p)
184 * :c:func:`PyObject_Free`
185 * * .. c:macro:: PyObject_DEL(p)
186 * :c:func:`PyObject_Free`
187 * * .. c:macro:: PyObject_Del(p)
188 * :c:func:`PyObject_Free`