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