jpayne@69: /* The PyObject_ memory family: high-level object memory interfaces. jpayne@69: See pymem.h for the low-level PyMem_ family. jpayne@69: */ jpayne@69: jpayne@69: #ifndef Py_OBJIMPL_H jpayne@69: #define Py_OBJIMPL_H jpayne@69: jpayne@69: #include "pymem.h" jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: jpayne@69: /* BEWARE: jpayne@69: jpayne@69: Each interface exports both functions and macros. Extension modules should jpayne@69: use the functions, to ensure binary compatibility across Python versions. jpayne@69: Because the Python implementation is free to change internal details, and jpayne@69: the macros may (or may not) expose details for speed, if you do use the jpayne@69: macros you must recompile your extensions with each Python release. jpayne@69: jpayne@69: Never mix calls to PyObject_ memory functions with calls to the platform jpayne@69: malloc/realloc/ calloc/free, or with calls to PyMem_. jpayne@69: */ jpayne@69: jpayne@69: /* jpayne@69: Functions and macros for modules that implement new object types. jpayne@69: jpayne@69: - PyObject_New(type, typeobj) allocates memory for a new object of the given jpayne@69: type, and initializes part of it. 'type' must be the C structure type used jpayne@69: to represent the object, and 'typeobj' the address of the corresponding jpayne@69: type object. Reference count and type pointer are filled in; the rest of jpayne@69: the bytes of the object are *undefined*! The resulting expression type is jpayne@69: 'type *'. The size of the object is determined by the tp_basicsize field jpayne@69: of the type object. jpayne@69: jpayne@69: - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size jpayne@69: object with room for n items. In addition to the refcount and type pointer jpayne@69: fields, this also fills in the ob_size field. jpayne@69: jpayne@69: - PyObject_Del(op) releases the memory allocated for an object. It does not jpayne@69: run a destructor -- it only frees the memory. PyObject_Free is identical. jpayne@69: jpayne@69: - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't jpayne@69: allocate memory. Instead of a 'type' parameter, they take a pointer to a jpayne@69: new object (allocated by an arbitrary allocator), and initialize its object jpayne@69: header fields. jpayne@69: jpayne@69: Note that objects created with PyObject_{New, NewVar} are allocated using the jpayne@69: specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is jpayne@69: enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG jpayne@69: is also #defined. jpayne@69: jpayne@69: In case a specific form of memory management is needed (for example, if you jpayne@69: must use the platform malloc heap(s), or shared memory, or C++ local storage or jpayne@69: operator new), you must first allocate the object with your custom allocator, jpayne@69: then pass its pointer to PyObject_{Init, InitVar} for filling in its Python- jpayne@69: specific fields: reference count, type pointer, possibly others. You should jpayne@69: be aware that Python has no control over these objects because they don't jpayne@69: cooperate with the Python memory manager. Such objects may not be eligible jpayne@69: for automatic garbage collection and you have to make sure that they are jpayne@69: released accordingly whenever their destructor gets called (cf. the specific jpayne@69: form of memory management you're using). jpayne@69: jpayne@69: Unless you have specific memory management requirements, use jpayne@69: PyObject_{New, NewVar, Del}. jpayne@69: */ jpayne@69: jpayne@69: /* jpayne@69: * Raw object memory interface jpayne@69: * =========================== jpayne@69: */ jpayne@69: jpayne@69: /* Functions to call the same malloc/realloc/free as used by Python's jpayne@69: object allocator. If WITH_PYMALLOC is enabled, these may differ from jpayne@69: the platform malloc/realloc/free. The Python object allocator is jpayne@69: designed for fast, cache-conscious allocation of many "small" objects, jpayne@69: and with low hidden memory overhead. jpayne@69: jpayne@69: PyObject_Malloc(0) returns a unique non-NULL pointer if possible. jpayne@69: jpayne@69: PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n). jpayne@69: PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory jpayne@69: at p. jpayne@69: jpayne@69: Returned pointers must be checked for NULL explicitly; no action is jpayne@69: performed on failure other than to return NULL (no warning it printed, no jpayne@69: exception is set, etc). jpayne@69: jpayne@69: For allocating objects, use PyObject_{New, NewVar} instead whenever jpayne@69: possible. The PyObject_{Malloc, Realloc, Free} family is exposed jpayne@69: so that you can exploit Python's small-block allocator for non-object jpayne@69: uses. If you must use these routines to allocate object memory, make sure jpayne@69: the object gets initialized via PyObject_{Init, InitVar} after obtaining jpayne@69: the raw memory. jpayne@69: */ jpayne@69: PyAPI_FUNC(void *) PyObject_Malloc(size_t size); jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 jpayne@69: PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize); jpayne@69: #endif jpayne@69: PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size); jpayne@69: PyAPI_FUNC(void) PyObject_Free(void *ptr); jpayne@69: jpayne@69: jpayne@69: /* Macros */ jpayne@69: #define PyObject_MALLOC PyObject_Malloc jpayne@69: #define PyObject_REALLOC PyObject_Realloc jpayne@69: #define PyObject_FREE PyObject_Free jpayne@69: #define PyObject_Del PyObject_Free jpayne@69: #define PyObject_DEL PyObject_Free jpayne@69: jpayne@69: jpayne@69: /* jpayne@69: * Generic object allocator interface jpayne@69: * ================================== jpayne@69: */ jpayne@69: jpayne@69: /* Functions */ jpayne@69: PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); jpayne@69: PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, jpayne@69: PyTypeObject *, Py_ssize_t); jpayne@69: PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); jpayne@69: PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); jpayne@69: jpayne@69: #define PyObject_New(type, typeobj) \ jpayne@69: ( (type *) _PyObject_New(typeobj) ) jpayne@69: #define PyObject_NewVar(type, typeobj, n) \ jpayne@69: ( (type *) _PyObject_NewVar((typeobj), (n)) ) jpayne@69: jpayne@69: /* Inline functions trading binary compatibility for speed: jpayne@69: PyObject_INIT() is the fast version of PyObject_Init(), and jpayne@69: PyObject_INIT_VAR() is the fast version of PyObject_InitVar. jpayne@69: See also pymem.h. jpayne@69: jpayne@69: These inline functions expect non-NULL object pointers. */ jpayne@69: static inline PyObject* jpayne@69: _PyObject_INIT(PyObject *op, PyTypeObject *typeobj) jpayne@69: { jpayne@69: assert(op != NULL); jpayne@69: Py_TYPE(op) = typeobj; jpayne@69: if (PyType_GetFlags(typeobj) & Py_TPFLAGS_HEAPTYPE) { jpayne@69: Py_INCREF(typeobj); jpayne@69: } jpayne@69: _Py_NewReference(op); jpayne@69: return op; jpayne@69: } jpayne@69: jpayne@69: #define PyObject_INIT(op, typeobj) \ jpayne@69: _PyObject_INIT(_PyObject_CAST(op), (typeobj)) jpayne@69: jpayne@69: static inline PyVarObject* jpayne@69: _PyObject_INIT_VAR(PyVarObject *op, PyTypeObject *typeobj, Py_ssize_t size) jpayne@69: { jpayne@69: assert(op != NULL); jpayne@69: Py_SIZE(op) = size; jpayne@69: PyObject_INIT((PyObject *)op, typeobj); jpayne@69: return op; jpayne@69: } jpayne@69: jpayne@69: #define PyObject_INIT_VAR(op, typeobj, size) \ jpayne@69: _PyObject_INIT_VAR(_PyVarObject_CAST(op), (typeobj), (size)) jpayne@69: jpayne@69: #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) jpayne@69: jpayne@69: /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a jpayne@69: vrbl-size object with nitems items, exclusive of gc overhead (if any). The jpayne@69: value is rounded up to the closest multiple of sizeof(void *), in order to jpayne@69: ensure that pointer fields at the end of the object are correctly aligned jpayne@69: for the platform (this is of special importance for subclasses of, e.g., jpayne@69: str or int, so that pointers can be stored after the embedded data). jpayne@69: jpayne@69: Note that there's no memory wastage in doing this, as malloc has to jpayne@69: return (at worst) pointer-aligned memory anyway. jpayne@69: */ jpayne@69: #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0 jpayne@69: # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2" jpayne@69: #endif jpayne@69: jpayne@69: #define _PyObject_VAR_SIZE(typeobj, nitems) \ jpayne@69: _Py_SIZE_ROUND_UP((typeobj)->tp_basicsize + \ jpayne@69: (nitems)*(typeobj)->tp_itemsize, \ jpayne@69: SIZEOF_VOID_P) jpayne@69: jpayne@69: #define PyObject_NEW(type, typeobj) \ jpayne@69: ( (type *) PyObject_Init( \ jpayne@69: (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) jpayne@69: jpayne@69: #define PyObject_NEW_VAR(type, typeobj, n) \ jpayne@69: ( (type *) PyObject_InitVar( \ jpayne@69: (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\ jpayne@69: (typeobj), (n)) ) jpayne@69: jpayne@69: /* This example code implements an object constructor with a custom jpayne@69: allocator, where PyObject_New is inlined, and shows the important jpayne@69: distinction between two steps (at least): jpayne@69: 1) the actual allocation of the object storage; jpayne@69: 2) the initialization of the Python specific fields jpayne@69: in this storage with PyObject_{Init, InitVar}. jpayne@69: jpayne@69: PyObject * jpayne@69: YourObject_New(...) jpayne@69: { jpayne@69: PyObject *op; jpayne@69: jpayne@69: op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); jpayne@69: if (op == NULL) jpayne@69: return PyErr_NoMemory(); jpayne@69: jpayne@69: PyObject_Init(op, &YourTypeStruct); jpayne@69: jpayne@69: op->ob_field = value; jpayne@69: ... jpayne@69: return op; jpayne@69: } jpayne@69: jpayne@69: Note that in C++, the use of the new operator usually implies that jpayne@69: the 1st step is performed automatically for you, so in a C++ class jpayne@69: constructor you would start directly with PyObject_Init/InitVar jpayne@69: */ jpayne@69: jpayne@69: jpayne@69: jpayne@69: /* jpayne@69: * Garbage Collection Support jpayne@69: * ========================== jpayne@69: */ jpayne@69: jpayne@69: /* C equivalent of gc.collect() which ignores the state of gc.enabled. */ jpayne@69: PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void); jpayne@69: jpayne@69: /* Test if a type has a GC head */ jpayne@69: #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) jpayne@69: jpayne@69: PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t); jpayne@69: #define PyObject_GC_Resize(type, op, n) \ jpayne@69: ( (type *) _PyObject_GC_Resize(_PyVarObject_CAST(op), (n)) ) jpayne@69: jpayne@69: jpayne@69: jpayne@69: PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); jpayne@69: PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); jpayne@69: jpayne@69: /* Tell the GC to track this object. jpayne@69: * jpayne@69: * See also private _PyObject_GC_TRACK() macro. */ jpayne@69: PyAPI_FUNC(void) PyObject_GC_Track(void *); jpayne@69: jpayne@69: /* Tell the GC to stop tracking this object. jpayne@69: * jpayne@69: * See also private _PyObject_GC_UNTRACK() macro. */ jpayne@69: PyAPI_FUNC(void) PyObject_GC_UnTrack(void *); jpayne@69: jpayne@69: PyAPI_FUNC(void) PyObject_GC_Del(void *); jpayne@69: jpayne@69: #define PyObject_GC_New(type, typeobj) \ jpayne@69: ( (type *) _PyObject_GC_New(typeobj) ) jpayne@69: #define PyObject_GC_NewVar(type, typeobj, n) \ jpayne@69: ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) jpayne@69: jpayne@69: jpayne@69: /* Utility macro to help write tp_traverse functions. jpayne@69: * To use this macro, the tp_traverse function must name its arguments jpayne@69: * "visit" and "arg". This is intended to keep tp_traverse functions jpayne@69: * looking as much alike as possible. jpayne@69: */ jpayne@69: #define Py_VISIT(op) \ jpayne@69: do { \ jpayne@69: if (op) { \ jpayne@69: int vret = visit(_PyObject_CAST(op), arg); \ jpayne@69: if (vret) \ jpayne@69: return vret; \ jpayne@69: } \ jpayne@69: } while (0) jpayne@69: jpayne@69: #ifndef Py_LIMITED_API jpayne@69: # define Py_CPYTHON_OBJIMPL_H jpayne@69: # include "cpython/objimpl.h" jpayne@69: # undef Py_CPYTHON_OBJIMPL_H jpayne@69: #endif jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } jpayne@69: #endif jpayne@69: #endif /* !Py_OBJIMPL_H */