| /* The PyObject_ memory family: high-level object memory interfaces. |
| See pymem.h for the low-level PyMem_ family. |
| */ |
| |
| #ifndef Py_OBJIMPL_H |
| #define Py_OBJIMPL_H |
| |
| #include "pymem.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /* BEWARE: |
| |
| Each interface exports both functions and macros. Extension modules should |
| use the functions, to ensure binary compatibility across Python versions. |
| Because the Python implementation is free to change internal details, and |
| the macros may (or may not) expose details for speed, if you do use the |
| macros you must recompile your extensions with each Python release. |
| |
| Never mix calls to PyObject_ memory functions with calls to the platform |
| malloc/realloc/ calloc/free, or with calls to PyMem_. |
| */ |
| |
| /* |
| Functions and macros for modules that implement new object types. |
| |
| - PyObject_New(type, typeobj) allocates memory for a new object of the given |
| type, and initializes part of it. 'type' must be the C structure type used |
| to represent the object, and 'typeobj' the address of the corresponding |
| type object. Reference count and type pointer are filled in; the rest of |
| the bytes of the object are *undefined*! The resulting expression type is |
| 'type *'. The size of the object is determined by the tp_basicsize field |
| of the type object. |
| |
| - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size |
| object with room for n items. In addition to the refcount and type pointer |
| fields, this also fills in the ob_size field. |
| |
| - PyObject_Del(op) releases the memory allocated for an object. It does not |
| run a destructor -- it only frees the memory. PyObject_Free is identical. |
| |
| - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't |
| allocate memory. Instead of a 'type' parameter, they take a pointer to a |
| new object (allocated by an arbitrary allocator), and initialize its object |
| header fields. |
| |
| Note that objects created with PyObject_{New, NewVar} are allocated using the |
| specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is |
| enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG |
| is also #defined. |
| |
| In case a specific form of memory management is needed (for example, if you |
| must use the platform malloc heap(s), or shared memory, or C++ local storage or |
| operator new), you must first allocate the object with your custom allocator, |
| then pass its pointer to PyObject_{Init, InitVar} for filling in its Python- |
| specific fields: reference count, type pointer, possibly others. You should |
| be aware that Python no control over these objects because they don't |
| cooperate with the Python memory manager. Such objects may not be eligible |
| for automatic garbage collection and you have to make sure that they are |
| released accordingly whenever their destructor gets called (cf. the specific |
| form of memory management you're using). |
| |
| Unless you have specific memory management requirements, use |
| PyObject_{New, NewVar, Del}. |
| */ |
| |
| /* |
| * Raw object memory interface |
| * =========================== |
| */ |
| |
| /* Functions to call the same malloc/realloc/free as used by Python's |
| object allocator. If WITH_PYMALLOC is enabled, these may differ from |
| the platform malloc/realloc/free. The Python object allocator is |
| designed for fast, cache-conscious allocation of many "small" objects, |
| and with low hidden memory overhead. |
| |
| PyObject_Malloc(0) returns a unique non-NULL pointer if possible. |
| |
| PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n). |
| PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory |
| at p. |
| |
| Returned pointers must be checked for NULL explicitly; no action is |
| performed on failure other than to return NULL (no warning it printed, no |
| exception is set, etc). |
| |
| For allocating objects, use PyObject_{New, NewVar} instead whenever |
| possible. The PyObject_{Malloc, Realloc, Free} family is exposed |
| so that you can exploit Python's small-block allocator for non-object |
| uses. If you must use these routines to allocate object memory, make sure |
| the object gets initialized via PyObject_{Init, InitVar} after obtaining |
| the raw memory. |
| */ |
| PyAPI_FUNC(void *) PyObject_Malloc(size_t); |
| PyAPI_FUNC(void *) PyObject_Realloc(void *, size_t); |
| PyAPI_FUNC(void) PyObject_Free(void *); |
| |
| |
| /* Macros */ |
| #ifdef WITH_PYMALLOC |
| #ifdef PYMALLOC_DEBUG |
| PyAPI_FUNC(void *) _PyObject_DebugMalloc(size_t nbytes); |
| PyAPI_FUNC(void *) _PyObject_DebugRealloc(void *p, size_t nbytes); |
| PyAPI_FUNC(void) _PyObject_DebugFree(void *p); |
| PyAPI_FUNC(void) _PyObject_DebugDumpAddress(const void *p); |
| PyAPI_FUNC(void) _PyObject_DebugCheckAddress(const void *p); |
| PyAPI_FUNC(void) _PyObject_DebugMallocStats(void); |
| #define PyObject_MALLOC _PyObject_DebugMalloc |
| #define PyObject_Malloc _PyObject_DebugMalloc |
| #define PyObject_REALLOC _PyObject_DebugRealloc |
| #define PyObject_Realloc _PyObject_DebugRealloc |
| #define PyObject_FREE _PyObject_DebugFree |
| #define PyObject_Free _PyObject_DebugFree |
| |
| #else /* WITH_PYMALLOC && ! PYMALLOC_DEBUG */ |
| #define PyObject_MALLOC PyObject_Malloc |
| #define PyObject_REALLOC PyObject_Realloc |
| #define PyObject_FREE PyObject_Free |
| #endif |
| |
| #else /* ! WITH_PYMALLOC */ |
| #define PyObject_MALLOC PyMem_MALLOC |
| #define PyObject_REALLOC PyMem_REALLOC |
| /* This is an odd one! For backward compatibility with old extensions, the |
| PyMem "release memory" functions have to invoke the object allocator's |
| free() function. When pymalloc isn't enabled, that leaves us using |
| the platform free(). */ |
| #define PyObject_FREE free |
| |
| #endif /* WITH_PYMALLOC */ |
| |
| #define PyObject_Del PyObject_Free |
| #define PyObject_DEL PyObject_FREE |
| |
| /* for source compatibility with 2.2 */ |
| #define _PyObject_Del PyObject_Free |
| |
| /* |
| * Generic object allocator interface |
| * ================================== |
| */ |
| |
| /* Functions */ |
| PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); |
| PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, |
| PyTypeObject *, Py_ssize_t); |
| PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); |
| PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); |
| |
| #define PyObject_New(type, typeobj) \ |
| ( (type *) _PyObject_New(typeobj) ) |
| #define PyObject_NewVar(type, typeobj, n) \ |
| ( (type *) _PyObject_NewVar((typeobj), (n)) ) |
| |
| /* Macros trading binary compatibility for speed. See also pymem.h. |
| Note that these macros expect non-NULL object pointers.*/ |
| #define PyObject_INIT(op, typeobj) \ |
| ( (op)->ob_type = (typeobj), _Py_NewReference((PyObject *)(op)), (op) ) |
| #define PyObject_INIT_VAR(op, typeobj, size) \ |
| ( (op)->ob_size = (size), PyObject_INIT((op), (typeobj)) ) |
| |
| #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) |
| |
| /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a |
| vrbl-size object with nitems items, exclusive of gc overhead (if any). The |
| value is rounded up to the closest multiple of sizeof(void *), in order to |
| ensure that pointer fields at the end of the object are correctly aligned |
| for the platform (this is of special importance for subclasses of, e.g., |
| str or long, so that pointers can be stored after the embedded data). |
| |
| Note that there's no memory wastage in doing this, as malloc has to |
| return (at worst) pointer-aligned memory anyway. |
| */ |
| #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0 |
| # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2" |
| #endif |
| |
| #define _PyObject_VAR_SIZE(typeobj, nitems) \ |
| (size_t) \ |
| ( ( (typeobj)->tp_basicsize + \ |
| (nitems)*(typeobj)->tp_itemsize + \ |
| (SIZEOF_VOID_P - 1) \ |
| ) & ~(SIZEOF_VOID_P - 1) \ |
| ) |
| |
| #define PyObject_NEW(type, typeobj) \ |
| ( (type *) PyObject_Init( \ |
| (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) |
| |
| #define PyObject_NEW_VAR(type, typeobj, n) \ |
| ( (type *) PyObject_InitVar( \ |
| (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\ |
| (typeobj), (n)) ) |
| |
| /* This example code implements an object constructor with a custom |
| allocator, where PyObject_New is inlined, and shows the important |
| distinction between two steps (at least): |
| 1) the actual allocation of the object storage; |
| 2) the initialization of the Python specific fields |
| in this storage with PyObject_{Init, InitVar}. |
| |
| PyObject * |
| YourObject_New(...) |
| { |
| PyObject *op; |
| |
| op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); |
| if (op == NULL) |
| return PyErr_NoMemory(); |
| |
| PyObject_Init(op, &YourTypeStruct); |
| |
| op->ob_field = value; |
| ... |
| return op; |
| } |
| |
| Note that in C++, the use of the new operator usually implies that |
| the 1st step is performed automatically for you, so in a C++ class |
| constructor you would start directly with PyObject_Init/InitVar |
| */ |
| |
| /* |
| * Garbage Collection Support |
| * ========================== |
| */ |
| |
| /* C equivalent of gc.collect(). */ |
| PyAPI_FUNC(long) PyGC_Collect(void); |
| |
| /* Test if a type has a GC head */ |
| #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) |
| |
| /* Test if an object has a GC head */ |
| #define PyObject_IS_GC(o) (PyType_IS_GC((o)->ob_type) && \ |
| ((o)->ob_type->tp_is_gc == NULL || (o)->ob_type->tp_is_gc(o))) |
| |
| PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, int); |
| #define PyObject_GC_Resize(type, op, n) \ |
| ( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) ) |
| |
| /* for source compatibility with 2.2 */ |
| #define _PyObject_GC_Del PyObject_GC_Del |
| |
| /* GC information is stored BEFORE the object structure. */ |
| typedef union _gc_head { |
| struct { |
| union _gc_head *gc_next; |
| union _gc_head *gc_prev; |
| int gc_refs; |
| } gc; |
| long double dummy; /* force worst-case alignment */ |
| } PyGC_Head; |
| |
| extern PyGC_Head *_PyGC_generation0; |
| |
| #define _Py_AS_GC(o) ((PyGC_Head *)(o)-1) |
| |
| #define _PyGC_REFS_UNTRACKED (-2) |
| #define _PyGC_REFS_REACHABLE (-3) |
| #define _PyGC_REFS_TENTATIVELY_UNREACHABLE (-4) |
| |
| /* Tell the GC to track this object. NB: While the object is tracked the |
| * collector it must be safe to call the ob_traverse method. */ |
| #define _PyObject_GC_TRACK(o) do { \ |
| PyGC_Head *g = _Py_AS_GC(o); \ |
| if (g->gc.gc_refs != _PyGC_REFS_UNTRACKED) \ |
| Py_FatalError("GC object already tracked"); \ |
| g->gc.gc_refs = _PyGC_REFS_REACHABLE; \ |
| g->gc.gc_next = _PyGC_generation0; \ |
| g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \ |
| g->gc.gc_prev->gc.gc_next = g; \ |
| _PyGC_generation0->gc.gc_prev = g; \ |
| } while (0); |
| |
| /* Tell the GC to stop tracking this object. |
| * gc_next doesn't need to be set to NULL, but doing so is a good |
| * way to provoke memory errors if calling code is confused. |
| */ |
| #define _PyObject_GC_UNTRACK(o) do { \ |
| PyGC_Head *g = _Py_AS_GC(o); \ |
| assert(g->gc.gc_refs != _PyGC_REFS_UNTRACKED); \ |
| g->gc.gc_refs = _PyGC_REFS_UNTRACKED; \ |
| g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \ |
| g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \ |
| g->gc.gc_next = NULL; \ |
| } while (0); |
| |
| PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t); |
| PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); |
| PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); |
| PyAPI_FUNC(void) PyObject_GC_Track(void *); |
| PyAPI_FUNC(void) PyObject_GC_UnTrack(void *); |
| PyAPI_FUNC(void) PyObject_GC_Del(void *); |
| |
| #define PyObject_GC_New(type, typeobj) \ |
| ( (type *) _PyObject_GC_New(typeobj) ) |
| #define PyObject_GC_NewVar(type, typeobj, n) \ |
| ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) |
| |
| |
| /* Utility macro to help write tp_traverse functions. |
| * To use this macro, the tp_traverse function must name its arguments |
| * "visit" and "arg". This is intended to keep tp_traverse functions |
| * looking as much alike as possible. |
| */ |
| #define Py_VISIT(op) \ |
| do { \ |
| if (op) { \ |
| int vret = visit((op), arg); \ |
| if (vret) \ |
| return vret; \ |
| } \ |
| } while (0) |
| |
| /* This is here for the sake of backwards compatibility. Extensions that |
| * use the old GC API will still compile but the objects will not be |
| * tracked by the GC. */ |
| #define PyGC_HEAD_SIZE 0 |
| #define PyObject_GC_Init(op) |
| #define PyObject_GC_Fini(op) |
| #define PyObject_AS_GC(op) (op) |
| #define PyObject_FROM_GC(op) (op) |
| |
| |
| /* Test if a type supports weak references */ |
| #define PyType_SUPPORTS_WEAKREFS(t) \ |
| (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \ |
| && ((t)->tp_weaklistoffset > 0)) |
| |
| #define PyObject_GET_WEAKREFS_LISTPTR(o) \ |
| ((PyObject **) (((char *) (o)) + (o)->ob_type->tp_weaklistoffset)) |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| #endif /* !Py_OBJIMPL_H */ |