| 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` |