Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 1 | /* The PyObject_ memory family: high-level object memory interfaces. |
| 2 | See pymem.h for the low-level PyMem_ family. |
| 3 | */ |
| 4 | |
| 5 | #ifndef Py_OBJIMPL_H |
| 6 | #define Py_OBJIMPL_H |
| 7 | |
| 8 | #include "pymem.h" |
| 9 | |
| 10 | #ifdef __cplusplus |
| 11 | extern "C" { |
| 12 | #endif |
| 13 | |
| 14 | /* BEWARE: |
| 15 | |
| 16 | Each interface exports both functions and macros. Extension modules should |
| 17 | use the functions, to ensure binary compatibility across Python versions. |
| 18 | Because the Python implementation is free to change internal details, and |
| 19 | the macros may (or may not) expose details for speed, if you do use the |
| 20 | macros you must recompile your extensions with each Python release. |
| 21 | |
| 22 | Never mix calls to PyObject_ memory functions with calls to the platform |
| 23 | malloc/realloc/ calloc/free, or with calls to PyMem_. |
| 24 | */ |
| 25 | |
| 26 | /* |
| 27 | Functions and macros for modules that implement new object types. |
| 28 | |
| 29 | - PyObject_New(type, typeobj) allocates memory for a new object of the given |
| 30 | type, and initializes part of it. 'type' must be the C structure type used |
| 31 | to represent the object, and 'typeobj' the address of the corresponding |
| 32 | type object. Reference count and type pointer are filled in; the rest of |
| 33 | the bytes of the object are *undefined*! The resulting expression type is |
| 34 | 'type *'. The size of the object is determined by the tp_basicsize field |
| 35 | of the type object. |
| 36 | |
| 37 | - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size |
| 38 | object with room for n items. In addition to the refcount and type pointer |
| 39 | fields, this also fills in the ob_size field. |
| 40 | |
| 41 | - PyObject_Del(op) releases the memory allocated for an object. It does not |
| 42 | run a destructor -- it only frees the memory. PyObject_Free is identical. |
| 43 | |
| 44 | - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't |
| 45 | allocate memory. Instead of a 'type' parameter, they take a pointer to a |
| 46 | new object (allocated by an arbitrary allocator), and initialize its object |
| 47 | header fields. |
| 48 | |
| 49 | Note that objects created with PyObject_{New, NewVar} are allocated using the |
| 50 | specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is |
| 51 | enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG |
| 52 | is also #defined. |
| 53 | |
| 54 | In case a specific form of memory management is needed (for example, if you |
| 55 | must use the platform malloc heap(s), or shared memory, or C++ local storage or |
| 56 | operator new), you must first allocate the object with your custom allocator, |
| 57 | then pass its pointer to PyObject_{Init, InitVar} for filling in its Python- |
| 58 | specific fields: reference count, type pointer, possibly others. You should |
| 59 | be aware that Python has no control over these objects because they don't |
| 60 | cooperate with the Python memory manager. Such objects may not be eligible |
| 61 | for automatic garbage collection and you have to make sure that they are |
| 62 | released accordingly whenever their destructor gets called (cf. the specific |
| 63 | form of memory management you're using). |
| 64 | |
| 65 | Unless you have specific memory management requirements, use |
| 66 | PyObject_{New, NewVar, Del}. |
| 67 | */ |
| 68 | |
| 69 | /* |
| 70 | * Raw object memory interface |
| 71 | * =========================== |
| 72 | */ |
| 73 | |
| 74 | /* Functions to call the same malloc/realloc/free as used by Python's |
| 75 | object allocator. If WITH_PYMALLOC is enabled, these may differ from |
| 76 | the platform malloc/realloc/free. The Python object allocator is |
| 77 | designed for fast, cache-conscious allocation of many "small" objects, |
| 78 | and with low hidden memory overhead. |
| 79 | |
| 80 | PyObject_Malloc(0) returns a unique non-NULL pointer if possible. |
| 81 | |
| 82 | PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n). |
| 83 | PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory |
| 84 | at p. |
| 85 | |
| 86 | Returned pointers must be checked for NULL explicitly; no action is |
| 87 | performed on failure other than to return NULL (no warning it printed, no |
| 88 | exception is set, etc). |
| 89 | |
| 90 | For allocating objects, use PyObject_{New, NewVar} instead whenever |
| 91 | possible. The PyObject_{Malloc, Realloc, Free} family is exposed |
| 92 | so that you can exploit Python's small-block allocator for non-object |
| 93 | uses. If you must use these routines to allocate object memory, make sure |
| 94 | the object gets initialized via PyObject_{Init, InitVar} after obtaining |
| 95 | the raw memory. |
| 96 | */ |
| 97 | PyAPI_FUNC(void *) PyObject_Malloc(size_t size); |
| 98 | #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 |
| 99 | PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize); |
| 100 | #endif |
| 101 | PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size); |
| 102 | PyAPI_FUNC(void) PyObject_Free(void *ptr); |
| 103 | |
| 104 | |
| 105 | /* Macros */ |
| 106 | #define PyObject_MALLOC PyObject_Malloc |
| 107 | #define PyObject_REALLOC PyObject_Realloc |
| 108 | #define PyObject_FREE PyObject_Free |
| 109 | #define PyObject_Del PyObject_Free |
| 110 | #define PyObject_DEL PyObject_Free |
| 111 | |
| 112 | |
| 113 | /* |
| 114 | * Generic object allocator interface |
| 115 | * ================================== |
| 116 | */ |
| 117 | |
| 118 | /* Functions */ |
| 119 | PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); |
| 120 | PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, |
| 121 | PyTypeObject *, Py_ssize_t); |
| 122 | PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); |
| 123 | PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); |
| 124 | |
| 125 | #define PyObject_New(type, typeobj) ((type *)_PyObject_New(typeobj)) |
| 126 | |
| 127 | // Alias to PyObject_New(). In Python 3.8, PyObject_NEW() called directly |
| 128 | // PyObject_MALLOC() with _PyObject_SIZE(). |
| 129 | #define PyObject_NEW(type, typeobj) PyObject_New(type, typeobj) |
| 130 | |
| 131 | #define PyObject_NewVar(type, typeobj, n) \ |
| 132 | ( (type *) _PyObject_NewVar((typeobj), (n)) ) |
| 133 | |
| 134 | // Alias to PyObject_New(). In Python 3.8, PyObject_NEW() called directly |
| 135 | // PyObject_MALLOC() with _PyObject_VAR_SIZE(). |
| 136 | #define PyObject_NEW_VAR(type, typeobj, n) PyObject_NewVar(type, typeobj, n) |
| 137 | |
| 138 | |
| 139 | #ifdef Py_LIMITED_API |
| 140 | /* Define PyObject_INIT() and PyObject_INIT_VAR() as aliases to PyObject_Init() |
| 141 | and PyObject_InitVar() in the limited C API for compatibility with the |
| 142 | CPython C API. */ |
| 143 | # define PyObject_INIT(op, typeobj) \ |
| 144 | PyObject_Init(_PyObject_CAST(op), (typeobj)) |
| 145 | # define PyObject_INIT_VAR(op, typeobj, size) \ |
| 146 | PyObject_InitVar(_PyVarObject_CAST(op), (typeobj), (size)) |
| 147 | #else |
| 148 | /* PyObject_INIT() and PyObject_INIT_VAR() are defined in cpython/objimpl.h */ |
| 149 | #endif |
| 150 | |
| 151 | |
| 152 | /* |
| 153 | * Garbage Collection Support |
| 154 | * ========================== |
| 155 | */ |
| 156 | |
| 157 | /* C equivalent of gc.collect() which ignores the state of gc.enabled. */ |
| 158 | PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void); |
| 159 | |
| 160 | /* Test if a type has a GC head */ |
| 161 | #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) |
| 162 | |
| 163 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t); |
| 164 | #define PyObject_GC_Resize(type, op, n) \ |
| 165 | ( (type *) _PyObject_GC_Resize(_PyVarObject_CAST(op), (n)) ) |
| 166 | |
| 167 | |
| 168 | |
| 169 | PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); |
| 170 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); |
| 171 | |
| 172 | /* Tell the GC to track this object. |
| 173 | * |
| 174 | * See also private _PyObject_GC_TRACK() macro. */ |
| 175 | PyAPI_FUNC(void) PyObject_GC_Track(void *); |
| 176 | |
| 177 | /* Tell the GC to stop tracking this object. |
| 178 | * |
| 179 | * See also private _PyObject_GC_UNTRACK() macro. */ |
| 180 | PyAPI_FUNC(void) PyObject_GC_UnTrack(void *); |
| 181 | |
| 182 | PyAPI_FUNC(void) PyObject_GC_Del(void *); |
| 183 | |
| 184 | #define PyObject_GC_New(type, typeobj) \ |
| 185 | ( (type *) _PyObject_GC_New(typeobj) ) |
| 186 | #define PyObject_GC_NewVar(type, typeobj, n) \ |
| 187 | ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) |
| 188 | |
| 189 | PyAPI_FUNC(int) PyObject_GC_IsTracked(PyObject *); |
| 190 | PyAPI_FUNC(int) PyObject_GC_IsFinalized(PyObject *); |
| 191 | |
| 192 | /* Utility macro to help write tp_traverse functions. |
| 193 | * To use this macro, the tp_traverse function must name its arguments |
| 194 | * "visit" and "arg". This is intended to keep tp_traverse functions |
| 195 | * looking as much alike as possible. |
| 196 | */ |
| 197 | #define Py_VISIT(op) \ |
| 198 | do { \ |
| 199 | if (op) { \ |
| 200 | int vret = visit(_PyObject_CAST(op), arg); \ |
| 201 | if (vret) \ |
| 202 | return vret; \ |
| 203 | } \ |
| 204 | } while (0) |
| 205 | |
| 206 | #ifndef Py_LIMITED_API |
| 207 | # define Py_CPYTHON_OBJIMPL_H |
| 208 | # include "cpython/objimpl.h" |
| 209 | # undef Py_CPYTHON_OBJIMPL_H |
| 210 | #endif |
| 211 | |
| 212 | #ifdef __cplusplus |
| 213 | } |
| 214 | #endif |
| 215 | #endif /* !Py_OBJIMPL_H */ |