Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _allocating-objects: |
| 4 | |
| 5 | Allocating Objects on the Heap |
| 6 | ============================== |
| 7 | |
| 8 | |
| 9 | .. cfunction:: PyObject* _PyObject_New(PyTypeObject *type) |
| 10 | |
| 11 | |
| 12 | .. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size) |
| 13 | |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame^] | 14 | .. versionchanged:: 2.5 |
| 15 | This function used an :ctype:`int` type for *size*. This might require |
| 16 | changes in your code for properly supporting 64-bit systems. |
| 17 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 18 | |
| 19 | .. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type) |
| 20 | |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame^] | 21 | Initialize a newly-allocated object *op* with its type and initial |
| 22 | reference. Returns the initialized object. If *type* indicates that the |
| 23 | object participates in the cyclic garbage detector, it is added to the |
| 24 | detector's set of observed objects. Other fields of the object are not |
| 25 | affected. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 26 | |
| 27 | |
| 28 | .. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size) |
| 29 | |
| 30 | This does everything :cfunc:`PyObject_Init` does, and also initializes the |
| 31 | length information for a variable-size object. |
| 32 | |
| 33 | |
| 34 | .. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type) |
| 35 | |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame^] | 36 | Allocate a new Python object using the C structure type *TYPE* and the |
| 37 | Python type object *type*. Fields not defined by the Python object header |
| 38 | are not initialized; the object's reference count will be one. The size of |
| 39 | the memory allocation is determined from the :attr:`tp_basicsize` field of |
| 40 | the type object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 41 | |
| 42 | |
| 43 | .. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) |
| 44 | |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame^] | 45 | Allocate a new Python object using the C structure type *TYPE* and the |
| 46 | Python type object *type*. Fields not defined by the Python object header |
| 47 | are not initialized. The allocated memory allows for the *TYPE* structure |
| 48 | plus *size* fields of the size given by the :attr:`tp_itemsize` field of |
| 49 | *type*. This is useful for implementing objects like tuples, which are |
| 50 | able to determine their size at construction time. Embedding the array of |
| 51 | fields into the same allocation decreases the number of allocations, |
| 52 | improving the memory management efficiency. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 53 | |
| 54 | |
| 55 | .. cfunction:: void PyObject_Del(PyObject *op) |
| 56 | |
| 57 | Releases memory allocated to an object using :cfunc:`PyObject_New` or |
Jeroen Ruigrok van der Werven | bd87552 | 2009-04-26 21:06:15 +0000 | [diff] [blame^] | 58 | :cfunc:`PyObject_NewVar`. This is normally called from the |
| 59 | :attr:`tp_dealloc` handler specified in the object's type. The fields of |
| 60 | the object should not be accessed after this call as the memory is no |
| 61 | longer a valid Python object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 62 | |
| 63 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 64 | .. cvar:: PyObject _Py_NoneStruct |
| 65 | |
| 66 | Object which is visible in Python as ``None``. This should only be accessed |
| 67 | using the :cmacro:`Py_None` macro, which evaluates to a pointer to this |
| 68 | object. |
Georg Brandl | e69cdf9 | 2009-01-04 23:20:14 +0000 | [diff] [blame] | 69 | |
| 70 | |
| 71 | .. seealso:: |
| 72 | |
| 73 | :cfunc:`PyModule_Create` |
| 74 | To allocate and create extension modules. |
| 75 | |