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