mirror of
https://github.com/python/cpython.git
synced 2025-10-30 18:07:37 +00:00
93 lines
3.9 KiB
ReStructuredText
93 lines
3.9 KiB
ReStructuredText
.. highlightlang:: c
|
|
|
|
.. _allocating-objects:
|
|
|
|
Allocating Objects on the Heap
|
|
==============================
|
|
|
|
|
|
.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
|
|
|
|
|
|
.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
|
|
|
|
|
|
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
|
|
|
|
Initialize a newly-allocated object *op* with its type and initial reference.
|
|
Returns the initialized object. If *type* indicates that the object
|
|
participates in the cyclic garbage detector, it is added to the detector's set
|
|
of observed objects. Other fields of the object are not affected.
|
|
|
|
|
|
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
|
|
|
|
This does everything :cfunc:`PyObject_Init` does, and also initializes the
|
|
length information for a variable-size object.
|
|
|
|
|
|
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
|
|
|
|
Allocate a new Python object using the C structure type *TYPE* and the Python
|
|
type object *type*. Fields not defined by the Python object header are not
|
|
initialized; the object's reference count will be one. The size of the memory
|
|
allocation is determined from the :attr:`tp_basicsize` field of the type object.
|
|
|
|
|
|
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
|
|
|
|
Allocate a new Python object using the C structure type *TYPE* and the Python
|
|
type object *type*. Fields not defined by the Python object header are not
|
|
initialized. The allocated memory allows for the *TYPE* structure plus *size*
|
|
fields of the size given by the :attr:`tp_itemsize` field of *type*. This is
|
|
useful for implementing objects like tuples, which are able to determine their
|
|
size at construction time. Embedding the array of fields into the same
|
|
allocation decreases the number of allocations, improving the memory management
|
|
efficiency.
|
|
|
|
|
|
.. cfunction:: void PyObject_Del(PyObject *op)
|
|
|
|
Releases memory allocated to an object using :cfunc:`PyObject_New` or
|
|
:cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc`
|
|
handler specified in the object's type. The fields of the object should not be
|
|
accessed after this call as the memory is no longer a valid Python object.
|
|
|
|
|
|
.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
|
|
|
|
Create a new module object based on a name and table of functions, returning
|
|
the new module object; the *methods* argument can be *NULL* if no methods are
|
|
to be defined for the module.
|
|
|
|
|
|
.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
|
|
|
|
Create a new module object based on a name and table of functions, returning
|
|
the new module object. The *methods* argument can be *NULL* if no methods
|
|
are to be defined for the module. If *doc* is non-*NULL*, it will be used to
|
|
define the docstring for the module.
|
|
|
|
|
|
.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
|
|
|
|
Create a new module object based on a name and table of functions, returning
|
|
the new module object. The *methods* argument can be *NULL* if no methods
|
|
are to be defined for the module. If *doc* is non-*NULL*, it will be used to
|
|
define the docstring for the module. If *self* is non-*NULL*, it will passed
|
|
to the functions of the module as their (otherwise *NULL*) first parameter.
|
|
(This was added as an experimental feature, and there are no known uses in
|
|
the current version of Python.) For *apiver*, the only value which should be
|
|
passed is defined by the constant :const:`PYTHON_API_VERSION`.
|
|
|
|
.. note::
|
|
|
|
Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
|
|
instead; only use this if you are sure you need it.
|
|
|
|
|
|
.. cvar:: PyObject _Py_NoneStruct
|
|
|
|
Object which is visible in Python as ``None``. This should only be accessed
|
|
using the :cmacro:`Py_None` macro, which evaluates to a pointer to this
|
|
object.
|