Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/python3.8/objimpl.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 /* The PyObject_ memory family: high-level object memory interfaces.
jpayne@69 2 See pymem.h for the low-level PyMem_ family.
jpayne@69 3 */
jpayne@69 4
jpayne@69 5 #ifndef Py_OBJIMPL_H
jpayne@69 6 #define Py_OBJIMPL_H
jpayne@69 7
jpayne@69 8 #include "pymem.h"
jpayne@69 9
jpayne@69 10 #ifdef __cplusplus
jpayne@69 11 extern "C" {
jpayne@69 12 #endif
jpayne@69 13
jpayne@69 14 /* BEWARE:
jpayne@69 15
jpayne@69 16 Each interface exports both functions and macros. Extension modules should
jpayne@69 17 use the functions, to ensure binary compatibility across Python versions.
jpayne@69 18 Because the Python implementation is free to change internal details, and
jpayne@69 19 the macros may (or may not) expose details for speed, if you do use the
jpayne@69 20 macros you must recompile your extensions with each Python release.
jpayne@69 21
jpayne@69 22 Never mix calls to PyObject_ memory functions with calls to the platform
jpayne@69 23 malloc/realloc/ calloc/free, or with calls to PyMem_.
jpayne@69 24 */
jpayne@69 25
jpayne@69 26 /*
jpayne@69 27 Functions and macros for modules that implement new object types.
jpayne@69 28
jpayne@69 29 - PyObject_New(type, typeobj) allocates memory for a new object of the given
jpayne@69 30 type, and initializes part of it. 'type' must be the C structure type used
jpayne@69 31 to represent the object, and 'typeobj' the address of the corresponding
jpayne@69 32 type object. Reference count and type pointer are filled in; the rest of
jpayne@69 33 the bytes of the object are *undefined*! The resulting expression type is
jpayne@69 34 'type *'. The size of the object is determined by the tp_basicsize field
jpayne@69 35 of the type object.
jpayne@69 36
jpayne@69 37 - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size
jpayne@69 38 object with room for n items. In addition to the refcount and type pointer
jpayne@69 39 fields, this also fills in the ob_size field.
jpayne@69 40
jpayne@69 41 - PyObject_Del(op) releases the memory allocated for an object. It does not
jpayne@69 42 run a destructor -- it only frees the memory. PyObject_Free is identical.
jpayne@69 43
jpayne@69 44 - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't
jpayne@69 45 allocate memory. Instead of a 'type' parameter, they take a pointer to a
jpayne@69 46 new object (allocated by an arbitrary allocator), and initialize its object
jpayne@69 47 header fields.
jpayne@69 48
jpayne@69 49 Note that objects created with PyObject_{New, NewVar} are allocated using the
jpayne@69 50 specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is
jpayne@69 51 enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG
jpayne@69 52 is also #defined.
jpayne@69 53
jpayne@69 54 In case a specific form of memory management is needed (for example, if you
jpayne@69 55 must use the platform malloc heap(s), or shared memory, or C++ local storage or
jpayne@69 56 operator new), you must first allocate the object with your custom allocator,
jpayne@69 57 then pass its pointer to PyObject_{Init, InitVar} for filling in its Python-
jpayne@69 58 specific fields: reference count, type pointer, possibly others. You should
jpayne@69 59 be aware that Python has no control over these objects because they don't
jpayne@69 60 cooperate with the Python memory manager. Such objects may not be eligible
jpayne@69 61 for automatic garbage collection and you have to make sure that they are
jpayne@69 62 released accordingly whenever their destructor gets called (cf. the specific
jpayne@69 63 form of memory management you're using).
jpayne@69 64
jpayne@69 65 Unless you have specific memory management requirements, use
jpayne@69 66 PyObject_{New, NewVar, Del}.
jpayne@69 67 */
jpayne@69 68
jpayne@69 69 /*
jpayne@69 70 * Raw object memory interface
jpayne@69 71 * ===========================
jpayne@69 72 */
jpayne@69 73
jpayne@69 74 /* Functions to call the same malloc/realloc/free as used by Python's
jpayne@69 75 object allocator. If WITH_PYMALLOC is enabled, these may differ from
jpayne@69 76 the platform malloc/realloc/free. The Python object allocator is
jpayne@69 77 designed for fast, cache-conscious allocation of many "small" objects,
jpayne@69 78 and with low hidden memory overhead.
jpayne@69 79
jpayne@69 80 PyObject_Malloc(0) returns a unique non-NULL pointer if possible.
jpayne@69 81
jpayne@69 82 PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n).
jpayne@69 83 PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory
jpayne@69 84 at p.
jpayne@69 85
jpayne@69 86 Returned pointers must be checked for NULL explicitly; no action is
jpayne@69 87 performed on failure other than to return NULL (no warning it printed, no
jpayne@69 88 exception is set, etc).
jpayne@69 89
jpayne@69 90 For allocating objects, use PyObject_{New, NewVar} instead whenever
jpayne@69 91 possible. The PyObject_{Malloc, Realloc, Free} family is exposed
jpayne@69 92 so that you can exploit Python's small-block allocator for non-object
jpayne@69 93 uses. If you must use these routines to allocate object memory, make sure
jpayne@69 94 the object gets initialized via PyObject_{Init, InitVar} after obtaining
jpayne@69 95 the raw memory.
jpayne@69 96 */
jpayne@69 97 PyAPI_FUNC(void *) PyObject_Malloc(size_t size);
jpayne@69 98 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
jpayne@69 99 PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize);
jpayne@69 100 #endif
jpayne@69 101 PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size);
jpayne@69 102 PyAPI_FUNC(void) PyObject_Free(void *ptr);
jpayne@69 103
jpayne@69 104
jpayne@69 105 /* Macros */
jpayne@69 106 #define PyObject_MALLOC PyObject_Malloc
jpayne@69 107 #define PyObject_REALLOC PyObject_Realloc
jpayne@69 108 #define PyObject_FREE PyObject_Free
jpayne@69 109 #define PyObject_Del PyObject_Free
jpayne@69 110 #define PyObject_DEL PyObject_Free
jpayne@69 111
jpayne@69 112
jpayne@69 113 /*
jpayne@69 114 * Generic object allocator interface
jpayne@69 115 * ==================================
jpayne@69 116 */
jpayne@69 117
jpayne@69 118 /* Functions */
jpayne@69 119 PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *);
jpayne@69 120 PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *,
jpayne@69 121 PyTypeObject *, Py_ssize_t);
jpayne@69 122 PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *);
jpayne@69 123 PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t);
jpayne@69 124
jpayne@69 125 #define PyObject_New(type, typeobj) \
jpayne@69 126 ( (type *) _PyObject_New(typeobj) )
jpayne@69 127 #define PyObject_NewVar(type, typeobj, n) \
jpayne@69 128 ( (type *) _PyObject_NewVar((typeobj), (n)) )
jpayne@69 129
jpayne@69 130 /* Inline functions trading binary compatibility for speed:
jpayne@69 131 PyObject_INIT() is the fast version of PyObject_Init(), and
jpayne@69 132 PyObject_INIT_VAR() is the fast version of PyObject_InitVar.
jpayne@69 133 See also pymem.h.
jpayne@69 134
jpayne@69 135 These inline functions expect non-NULL object pointers. */
jpayne@69 136 static inline PyObject*
jpayne@69 137 _PyObject_INIT(PyObject *op, PyTypeObject *typeobj)
jpayne@69 138 {
jpayne@69 139 assert(op != NULL);
jpayne@69 140 Py_TYPE(op) = typeobj;
jpayne@69 141 if (PyType_GetFlags(typeobj) & Py_TPFLAGS_HEAPTYPE) {
jpayne@69 142 Py_INCREF(typeobj);
jpayne@69 143 }
jpayne@69 144 _Py_NewReference(op);
jpayne@69 145 return op;
jpayne@69 146 }
jpayne@69 147
jpayne@69 148 #define PyObject_INIT(op, typeobj) \
jpayne@69 149 _PyObject_INIT(_PyObject_CAST(op), (typeobj))
jpayne@69 150
jpayne@69 151 static inline PyVarObject*
jpayne@69 152 _PyObject_INIT_VAR(PyVarObject *op, PyTypeObject *typeobj, Py_ssize_t size)
jpayne@69 153 {
jpayne@69 154 assert(op != NULL);
jpayne@69 155 Py_SIZE(op) = size;
jpayne@69 156 PyObject_INIT((PyObject *)op, typeobj);
jpayne@69 157 return op;
jpayne@69 158 }
jpayne@69 159
jpayne@69 160 #define PyObject_INIT_VAR(op, typeobj, size) \
jpayne@69 161 _PyObject_INIT_VAR(_PyVarObject_CAST(op), (typeobj), (size))
jpayne@69 162
jpayne@69 163 #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize )
jpayne@69 164
jpayne@69 165 /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a
jpayne@69 166 vrbl-size object with nitems items, exclusive of gc overhead (if any). The
jpayne@69 167 value is rounded up to the closest multiple of sizeof(void *), in order to
jpayne@69 168 ensure that pointer fields at the end of the object are correctly aligned
jpayne@69 169 for the platform (this is of special importance for subclasses of, e.g.,
jpayne@69 170 str or int, so that pointers can be stored after the embedded data).
jpayne@69 171
jpayne@69 172 Note that there's no memory wastage in doing this, as malloc has to
jpayne@69 173 return (at worst) pointer-aligned memory anyway.
jpayne@69 174 */
jpayne@69 175 #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0
jpayne@69 176 # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2"
jpayne@69 177 #endif
jpayne@69 178
jpayne@69 179 #define _PyObject_VAR_SIZE(typeobj, nitems) \
jpayne@69 180 _Py_SIZE_ROUND_UP((typeobj)->tp_basicsize + \
jpayne@69 181 (nitems)*(typeobj)->tp_itemsize, \
jpayne@69 182 SIZEOF_VOID_P)
jpayne@69 183
jpayne@69 184 #define PyObject_NEW(type, typeobj) \
jpayne@69 185 ( (type *) PyObject_Init( \
jpayne@69 186 (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) )
jpayne@69 187
jpayne@69 188 #define PyObject_NEW_VAR(type, typeobj, n) \
jpayne@69 189 ( (type *) PyObject_InitVar( \
jpayne@69 190 (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\
jpayne@69 191 (typeobj), (n)) )
jpayne@69 192
jpayne@69 193 /* This example code implements an object constructor with a custom
jpayne@69 194 allocator, where PyObject_New is inlined, and shows the important
jpayne@69 195 distinction between two steps (at least):
jpayne@69 196 1) the actual allocation of the object storage;
jpayne@69 197 2) the initialization of the Python specific fields
jpayne@69 198 in this storage with PyObject_{Init, InitVar}.
jpayne@69 199
jpayne@69 200 PyObject *
jpayne@69 201 YourObject_New(...)
jpayne@69 202 {
jpayne@69 203 PyObject *op;
jpayne@69 204
jpayne@69 205 op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct));
jpayne@69 206 if (op == NULL)
jpayne@69 207 return PyErr_NoMemory();
jpayne@69 208
jpayne@69 209 PyObject_Init(op, &YourTypeStruct);
jpayne@69 210
jpayne@69 211 op->ob_field = value;
jpayne@69 212 ...
jpayne@69 213 return op;
jpayne@69 214 }
jpayne@69 215
jpayne@69 216 Note that in C++, the use of the new operator usually implies that
jpayne@69 217 the 1st step is performed automatically for you, so in a C++ class
jpayne@69 218 constructor you would start directly with PyObject_Init/InitVar
jpayne@69 219 */
jpayne@69 220
jpayne@69 221
jpayne@69 222
jpayne@69 223 /*
jpayne@69 224 * Garbage Collection Support
jpayne@69 225 * ==========================
jpayne@69 226 */
jpayne@69 227
jpayne@69 228 /* C equivalent of gc.collect() which ignores the state of gc.enabled. */
jpayne@69 229 PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void);
jpayne@69 230
jpayne@69 231 /* Test if a type has a GC head */
jpayne@69 232 #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)
jpayne@69 233
jpayne@69 234 PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t);
jpayne@69 235 #define PyObject_GC_Resize(type, op, n) \
jpayne@69 236 ( (type *) _PyObject_GC_Resize(_PyVarObject_CAST(op), (n)) )
jpayne@69 237
jpayne@69 238
jpayne@69 239
jpayne@69 240 PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *);
jpayne@69 241 PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t);
jpayne@69 242
jpayne@69 243 /* Tell the GC to track this object.
jpayne@69 244 *
jpayne@69 245 * See also private _PyObject_GC_TRACK() macro. */
jpayne@69 246 PyAPI_FUNC(void) PyObject_GC_Track(void *);
jpayne@69 247
jpayne@69 248 /* Tell the GC to stop tracking this object.
jpayne@69 249 *
jpayne@69 250 * See also private _PyObject_GC_UNTRACK() macro. */
jpayne@69 251 PyAPI_FUNC(void) PyObject_GC_UnTrack(void *);
jpayne@69 252
jpayne@69 253 PyAPI_FUNC(void) PyObject_GC_Del(void *);
jpayne@69 254
jpayne@69 255 #define PyObject_GC_New(type, typeobj) \
jpayne@69 256 ( (type *) _PyObject_GC_New(typeobj) )
jpayne@69 257 #define PyObject_GC_NewVar(type, typeobj, n) \
jpayne@69 258 ( (type *) _PyObject_GC_NewVar((typeobj), (n)) )
jpayne@69 259
jpayne@69 260
jpayne@69 261 /* Utility macro to help write tp_traverse functions.
jpayne@69 262 * To use this macro, the tp_traverse function must name its arguments
jpayne@69 263 * "visit" and "arg". This is intended to keep tp_traverse functions
jpayne@69 264 * looking as much alike as possible.
jpayne@69 265 */
jpayne@69 266 #define Py_VISIT(op) \
jpayne@69 267 do { \
jpayne@69 268 if (op) { \
jpayne@69 269 int vret = visit(_PyObject_CAST(op), arg); \
jpayne@69 270 if (vret) \
jpayne@69 271 return vret; \
jpayne@69 272 } \
jpayne@69 273 } while (0)
jpayne@69 274
jpayne@69 275 #ifndef Py_LIMITED_API
jpayne@69 276 # define Py_CPYTHON_OBJIMPL_H
jpayne@69 277 # include "cpython/objimpl.h"
jpayne@69 278 # undef Py_CPYTHON_OBJIMPL_H
jpayne@69 279 #endif
jpayne@69 280
jpayne@69 281 #ifdef __cplusplus
jpayne@69 282 }
jpayne@69 283 #endif
jpayne@69 284 #endif /* !Py_OBJIMPL_H */