14710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* The PyObject_ memory family: high-level object memory interfaces. 24710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm See pymem.h for the low-level PyMem_ family. 34710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 44710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 54710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#ifndef Py_OBJIMPL_H 64710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define Py_OBJIMPL_H 74710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 84710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#include "pymem.h" 94710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 104710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#ifdef __cplusplus 114710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmextern "C" { 124710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif 134710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 144710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* BEWARE: 154710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 164710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Each interface exports both functions and macros. Extension modules should 174710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm use the functions, to ensure binary compatibility across Python versions. 184710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Because the Python implementation is free to change internal details, and 194710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the macros may (or may not) expose details for speed, if you do use the 204710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm macros you must recompile your extensions with each Python release. 214710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 224710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Never mix calls to PyObject_ memory functions with calls to the platform 234710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm malloc/realloc/ calloc/free, or with calls to PyMem_. 244710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 254710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 264710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* 274710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmFunctions and macros for modules that implement new object types. 284710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 294710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm - PyObject_New(type, typeobj) allocates memory for a new object of the given 304710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm type, and initializes part of it. 'type' must be the C structure type used 314710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm to represent the object, and 'typeobj' the address of the corresponding 324710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm type object. Reference count and type pointer are filled in; the rest of 334710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the bytes of the object are *undefined*! The resulting expression type is 344710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 'type *'. The size of the object is determined by the tp_basicsize field 354710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm of the type object. 364710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 374710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size 384710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm object with room for n items. In addition to the refcount and type pointer 394710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm fields, this also fills in the ob_size field. 404710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 414710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm - PyObject_Del(op) releases the memory allocated for an object. It does not 424710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm run a destructor -- it only frees the memory. PyObject_Free is identical. 434710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 444710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't 454710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm allocate memory. Instead of a 'type' parameter, they take a pointer to a 464710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm new object (allocated by an arbitrary allocator), and initialize its object 474710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm header fields. 484710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 494710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmNote that objects created with PyObject_{New, NewVar} are allocated using the 504710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmspecialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is 514710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmenabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG 524710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmis also #defined. 534710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 544710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmIn case a specific form of memory management is needed (for example, if you 554710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmmust use the platform malloc heap(s), or shared memory, or C++ local storage or 564710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmoperator new), you must first allocate the object with your custom allocator, 574710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmthen pass its pointer to PyObject_{Init, InitVar} for filling in its Python- 584710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmspecific fields: reference count, type pointer, possibly others. You should 594710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmbe aware that Python no control over these objects because they don't 604710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmcooperate with the Python memory manager. Such objects may not be eligible 614710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmfor automatic garbage collection and you have to make sure that they are 624710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmreleased accordingly whenever their destructor gets called (cf. the specific 634710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmform of memory management you're using). 644710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 654710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmUnless you have specific memory management requirements, use 664710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyObject_{New, NewVar, Del}. 674710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 684710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 694710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* 704710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * Raw object memory interface 714710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * =========================== 724710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm */ 734710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 744710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Functions to call the same malloc/realloc/free as used by Python's 754710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm object allocator. If WITH_PYMALLOC is enabled, these may differ from 764710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the platform malloc/realloc/free. The Python object allocator is 774710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm designed for fast, cache-conscious allocation of many "small" objects, 784710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm and with low hidden memory overhead. 794710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 804710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject_Malloc(0) returns a unique non-NULL pointer if possible. 814710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 824710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n). 834710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory 844710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm at p. 854710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 864710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Returned pointers must be checked for NULL explicitly; no action is 874710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm performed on failure other than to return NULL (no warning it printed, no 884710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm exception is set, etc). 894710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 904710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm For allocating objects, use PyObject_{New, NewVar} instead whenever 914710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm possible. The PyObject_{Malloc, Realloc, Free} family is exposed 924710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm so that you can exploit Python's small-block allocator for non-object 934710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm uses. If you must use these routines to allocate object memory, make sure 944710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the object gets initialized via PyObject_{Init, InitVar} after obtaining 954710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the raw memory. 964710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 974710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) PyObject_Malloc(size_t); 984710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) PyObject_Realloc(void *, size_t); 994710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) PyObject_Free(void *); 1004710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1014710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1024710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Macros */ 1034710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#ifdef WITH_PYMALLOC 1044710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#ifdef PYMALLOC_DEBUG /* WITH_PYMALLOC && PYMALLOC_DEBUG */ 1054710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyObject_DebugMalloc(size_t nbytes); 1064710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyObject_DebugRealloc(void *p, size_t nbytes); 1074710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugFree(void *p); 1084710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugDumpAddress(const void *p); 1094710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugCheckAddress(const void *p); 1104710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugMallocStats(void); 1114710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyObject_DebugMallocApi(char api, size_t nbytes); 1124710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyObject_DebugReallocApi(char api, void *p, size_t nbytes); 1134710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugFreeApi(char api, void *p); 1144710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyObject_DebugCheckAddressApi(char api, const void *p); 1154710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyMem_DebugMalloc(size_t nbytes); 1164710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void *) _PyMem_DebugRealloc(void *p, size_t nbytes); 1174710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) _PyMem_DebugFree(void *p); 1184710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_MALLOC _PyObject_DebugMalloc 1194710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_Malloc _PyObject_DebugMalloc 1204710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_REALLOC _PyObject_DebugRealloc 1214710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_Realloc _PyObject_DebugRealloc 1224710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_FREE _PyObject_DebugFree 1234710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_Free _PyObject_DebugFree 1244710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1254710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#else /* WITH_PYMALLOC && ! PYMALLOC_DEBUG */ 1264710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_MALLOC PyObject_Malloc 1274710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_REALLOC PyObject_Realloc 1284710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_FREE PyObject_Free 1294710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif 1304710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1314710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#else /* ! WITH_PYMALLOC */ 1324710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_MALLOC PyMem_MALLOC 1334710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_REALLOC PyMem_REALLOC 1344710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_FREE PyMem_FREE 1354710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1364710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif /* WITH_PYMALLOC */ 1374710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1384710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_Del PyObject_Free 1394710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_DEL PyObject_FREE 1404710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1414710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* for source compatibility with 2.2 */ 1424710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_Del PyObject_Free 1434710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1444710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* 1454710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * Generic object allocator interface 1464710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * ================================== 1474710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm */ 1484710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1494710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Functions */ 1504710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); 1514710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, 1524710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyTypeObject *, Py_ssize_t); 1534710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); 1544710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); 1554710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1564710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_New(type, typeobj) \ 1574710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( (type *) _PyObject_New(typeobj) ) 1584710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_NewVar(type, typeobj, n) \ 1594710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( (type *) _PyObject_NewVar((typeobj), (n)) ) 1604710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1614710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Macros trading binary compatibility for speed. See also pymem.h. 1624710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Note that these macros expect non-NULL object pointers.*/ 1634710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_INIT(op, typeobj) \ 1644710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( Py_TYPE(op) = (typeobj), _Py_NewReference((PyObject *)(op)), (op) ) 1654710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_INIT_VAR(op, typeobj, size) \ 1664710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( Py_SIZE(op) = (size), PyObject_INIT((op), (typeobj)) ) 1674710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1684710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) 1694710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1704710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a 1714710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm vrbl-size object with nitems items, exclusive of gc overhead (if any). The 1724710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm value is rounded up to the closest multiple of sizeof(void *), in order to 1734710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ensure that pointer fields at the end of the object are correctly aligned 1744710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm for the platform (this is of special importance for subclasses of, e.g., 1754710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm str or long, so that pointers can be stored after the embedded data). 1764710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1774710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Note that there's no memory wastage in doing this, as malloc has to 1784710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm return (at worst) pointer-aligned memory anyway. 1794710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 1804710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0 1814710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm# error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2" 1824710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif 1834710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1844710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_VAR_SIZE(typeobj, nitems) \ 1854710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (size_t) \ 1864710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( ( (typeobj)->tp_basicsize + \ 1874710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (nitems)*(typeobj)->tp_itemsize + \ 1884710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (SIZEOF_VOID_P - 1) \ 1894710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ) & ~(SIZEOF_VOID_P - 1) \ 1904710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ) 1914710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1924710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_NEW(type, typeobj) \ 1934710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm( (type *) PyObject_Init( \ 1944710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) 1954710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1964710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_NEW_VAR(type, typeobj, n) \ 1974710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm( (type *) PyObject_InitVar( \ 1984710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\ 1994710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (typeobj), (n)) ) 2004710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2014710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* This example code implements an object constructor with a custom 2024710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm allocator, where PyObject_New is inlined, and shows the important 2034710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm distinction between two steps (at least): 2044710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 1) the actual allocation of the object storage; 2054710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2) the initialization of the Python specific fields 2064710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm in this storage with PyObject_{Init, InitVar}. 2074710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2084710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject * 2094710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm YourObject_New(...) 2104710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm { 2114710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject *op; 2124710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2134710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); 2144710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm if (op == NULL) 2154710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm return PyErr_NoMemory(); 2164710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2174710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyObject_Init(op, &YourTypeStruct); 2184710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2194710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm op->ob_field = value; 2204710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ... 2214710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm return op; 2224710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } 2234710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2244710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Note that in C++, the use of the new operator usually implies that 2254710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm the 1st step is performed automatically for you, so in a C++ class 2264710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm constructor you would start directly with PyObject_Init/InitVar 2274710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm*/ 2284710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2294710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* 2304710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * Garbage Collection Support 2314710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * ========================== 2324710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm */ 2334710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2344710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* C equivalent of gc.collect(). */ 2354710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(Py_ssize_t) PyGC_Collect(void); 2364710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2374710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Test if a type has a GC head */ 2384710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) 2394710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2404710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Test if an object has a GC head */ 2414710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_IS_GC(o) (PyType_IS_GC(Py_TYPE(o)) && \ 2424710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (Py_TYPE(o)->tp_is_gc == NULL || Py_TYPE(o)->tp_is_gc(o))) 2434710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2444710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t); 2454710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GC_Resize(type, op, n) \ 2464710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) ) 2474710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2484710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* for source compatibility with 2.2 */ 2494710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_GC_Del PyObject_GC_Del 2504710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2514710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* GC information is stored BEFORE the object structure. */ 2524710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmtypedef union _gc_head { 2534710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm struct { 2544710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm union _gc_head *gc_next; 2554710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm union _gc_head *gc_prev; 2564710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Py_ssize_t gc_refs; 2574710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } gc; 2584710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm long double dummy; /* force worst-case alignment */ 2594710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm} PyGC_Head; 2604710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2614710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmextern PyGC_Head *_PyGC_generation0; 2624710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2634710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _Py_AS_GC(o) ((PyGC_Head *)(o)-1) 2644710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2654710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyGC_REFS_UNTRACKED (-2) 2664710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyGC_REFS_REACHABLE (-3) 2674710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyGC_REFS_TENTATIVELY_UNREACHABLE (-4) 2684710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2694710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Tell the GC to track this object. NB: While the object is tracked the 2704710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * collector it must be safe to call the ob_traverse method. */ 2714710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_GC_TRACK(o) do { \ 2724710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyGC_Head *g = _Py_AS_GC(o); \ 2734710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm if (g->gc.gc_refs != _PyGC_REFS_UNTRACKED) \ 2744710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm Py_FatalError("GC object already tracked"); \ 2754710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_refs = _PyGC_REFS_REACHABLE; \ 2764710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_next = _PyGC_generation0; \ 2774710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \ 2784710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_prev->gc.gc_next = g; \ 2794710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm _PyGC_generation0->gc.gc_prev = g; \ 2804710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } while (0); 2814710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2824710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Tell the GC to stop tracking this object. 2834710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * gc_next doesn't need to be set to NULL, but doing so is a good 2844710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * way to provoke memory errors if calling code is confused. 2854710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm */ 2864710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_GC_UNTRACK(o) do { \ 2874710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm PyGC_Head *g = _Py_AS_GC(o); \ 2884710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm assert(g->gc.gc_refs != _PyGC_REFS_UNTRACKED); \ 2894710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_refs = _PyGC_REFS_UNTRACKED; \ 2904710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \ 2914710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \ 2924710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm g->gc.gc_next = NULL; \ 2934710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } while (0); 2944710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2954710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* True if the object is currently tracked by the GC. */ 2964710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_GC_IS_TRACKED(o) \ 2974710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ((_Py_AS_GC(o))->gc.gc_refs != _PyGC_REFS_UNTRACKED) 2984710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 2994710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* True if the object may be tracked by the GC in the future, or already is. 3004710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm This can be useful to implement some optimizations. */ 3014710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define _PyObject_GC_MAY_BE_TRACKED(obj) \ 3024710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (PyObject_IS_GC(obj) && \ 3034710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (!PyTuple_CheckExact(obj) || _PyObject_GC_IS_TRACKED(obj))) 3044710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3054710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3064710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t); 3074710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); 3084710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); 3094710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) PyObject_GC_Track(void *); 3104710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) PyObject_GC_UnTrack(void *); 3114710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylmPyAPI_FUNC(void) PyObject_GC_Del(void *); 3124710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3134710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GC_New(type, typeobj) \ 3144710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( (type *) _PyObject_GC_New(typeobj) ) 3154710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GC_NewVar(type, typeobj, n) \ 3164710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) 3174710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3184710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3194710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Utility macro to help write tp_traverse functions. 3204710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * To use this macro, the tp_traverse function must name its arguments 3214710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * "visit" and "arg". This is intended to keep tp_traverse functions 3224710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * looking as much alike as possible. 3234710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm */ 3244710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define Py_VISIT(op) \ 3254710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm do { \ 3264710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm if (op) { \ 3274710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm int vret = visit((PyObject *)(op), arg); \ 3284710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm if (vret) \ 3294710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm return vret; \ 3304710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } \ 3314710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm } while (0) 3324710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3334710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* This is here for the sake of backwards compatibility. Extensions that 3344710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * use the old GC API will still compile but the objects will not be 3354710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm * tracked by the GC. */ 3364710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyGC_HEAD_SIZE 0 3374710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GC_Init(op) 3384710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GC_Fini(op) 3394710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_AS_GC(op) (op) 3404710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_FROM_GC(op) (op) 3414710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3424710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3434710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm/* Test if a type supports weak references */ 3444710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyType_SUPPORTS_WEAKREFS(t) \ 3454710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \ 3464710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm && ((t)->tp_weaklistoffset > 0)) 3474710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3484710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#define PyObject_GET_WEAKREFS_LISTPTR(o) \ 3494710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm ((PyObject **) (((char *) (o)) + Py_TYPE(o)->tp_weaklistoffset)) 3504710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm 3514710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#ifdef __cplusplus 3524710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm} 3534710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif 3544710c53dcad1ebf3755f3efb9e80ac24bd72a9b2darylm#endif /* !Py_OBJIMPL_H */ 355