1.. highlightlang:: c 2 3.. _allocating-objects: 4 5Allocating 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 .. versionchanged:: 2.5 15 This function used an :c:type:`int` type for *size*. This might require 16 changes in your code for properly supporting 64-bit systems. 17 18 19.. c:function:: void _PyObject_Del(PyObject *op) 20 21 22.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type) 23 24 Initialize a newly-allocated object *op* with its type and initial 25 reference. Returns the initialized object. If *type* indicates that the 26 object participates in the cyclic garbage detector, it is added to the 27 detector's set of observed objects. Other fields of the object are not 28 affected. 29 30 31.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size) 32 33 This does everything :c:func:`PyObject_Init` does, and also initializes the 34 length information for a variable-size object. 35 36 .. versionchanged:: 2.5 37 This function used an :c:type:`int` type for *size*. This might require 38 changes in your code for properly supporting 64-bit systems. 39 40 41.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type) 42 43 Allocate a new Python object using the C structure type *TYPE* and the 44 Python type object *type*. Fields not defined by the Python object header 45 are not initialized; the object's reference count will be one. The size of 46 the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of 47 the type object. 48 49 50.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) 51 52 Allocate a new Python object using the C structure type *TYPE* and the 53 Python type object *type*. Fields not defined by the Python object header 54 are not initialized. The allocated memory allows for the *TYPE* structure 55 plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of 56 *type*. This is useful for implementing objects like tuples, which are 57 able to determine their size at construction time. Embedding the array of 58 fields into the same allocation decreases the number of allocations, 59 improving the memory management efficiency. 60 61 .. versionchanged:: 2.5 62 This function used an :c:type:`int` type for *size*. This might require 63 changes in your code for properly supporting 64-bit systems. 64 65 66.. c:function:: void PyObject_Del(PyObject *op) 67 68 Releases memory allocated to an object using :c:func:`PyObject_New` or 69 :c:func:`PyObject_NewVar`. This is normally called from the 70 :c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of 71 the object should not be accessed after this call as the memory is no 72 longer a valid Python object. 73 74 75.. c:function:: PyObject* Py_InitModule(char *name, PyMethodDef *methods) 76 77 Create a new module object based on a name and table of functions, 78 returning the new module object. 79 80 .. versionchanged:: 2.3 81 Older versions of Python did not support *NULL* as the value for the 82 *methods* argument. 83 84 85.. c:function:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc) 86 87 Create a new module object based on a name and table of functions, 88 returning the new module object. If *doc* is non-*NULL*, it will be used 89 to define the docstring for the module. 90 91 .. versionchanged:: 2.3 92 Older versions of Python did not support *NULL* as the value for the 93 *methods* argument. 94 95 96.. c:function:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver) 97 98 Create a new module object based on a name and table of functions, 99 returning the new module object. If *doc* is non-*NULL*, it will be used 100 to define the docstring for the module. If *self* is non-*NULL*, it will 101 be passed to the functions of the module as their (otherwise *NULL*) first 102 parameter. (This was added as an experimental feature, and there are no 103 known uses in the current version of Python.) For *apiver*, the only value 104 which should be passed is defined by the constant 105 :const:`PYTHON_API_VERSION`. 106 107 .. note:: 108 109 Most uses of this function should probably be using the 110 :c:func:`Py_InitModule3` instead; only use this if you are sure you need 111 it. 112 113 .. versionchanged:: 2.3 114 Older versions of Python did not support *NULL* as the value for the 115 *methods* argument. 116 117 118.. c:var:: PyObject _Py_NoneStruct 119 120 Object which is visible in Python as ``None``. This should only be 121 accessed using the ``Py_None`` macro, which evaluates to a pointer to this 122 object. 123