python3.13/cpython/objimpl.h

0001 #ifndef Py_CPYTHON_OBJIMPL_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 static inline size_t _PyObject_SIZE(PyTypeObject *type) {
0006     return _Py_STATIC_CAST(size_t, type->tp_basicsize);
0007 }
0008
0009 /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a
0010    vrbl-size object with nitems items, exclusive of gc overhead (if any).  The
0011    value is rounded up to the closest multiple of sizeof(void *), in order to
0012    ensure that pointer fields at the end of the object are correctly aligned
0013    for the platform (this is of special importance for subclasses of, e.g.,
0014    str or int, so that pointers can be stored after the embedded data).
0015
0016    Note that there's no memory wastage in doing this, as malloc has to
0017    return (at worst) pointer-aligned memory anyway.
0018 */
0019 #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0
0020 #   error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2"
0021 #endif
0022
0023 static inline size_t _PyObject_VAR_SIZE(PyTypeObject *type, Py_ssize_t nitems) {
0024     size_t size = _Py_STATIC_CAST(size_t, type->tp_basicsize);
0025     size += _Py_STATIC_CAST(size_t, nitems) * _Py_STATIC_CAST(size_t, type->tp_itemsize);
0026     return _Py_SIZE_ROUND_UP(size, SIZEOF_VOID_P);
0027 }
0028
0029
0030 /* This example code implements an object constructor with a custom
0031    allocator, where PyObject_New is inlined, and shows the important
0032    distinction between two steps (at least):
0033        1) the actual allocation of the object storage;
0034        2) the initialization of the Python specific fields
0035       in this storage with PyObject_{Init, InitVar}.
0036
0037    PyObject *
0038    YourObject_New(...)
0039    {
0040        PyObject *op;
0041
0042        op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct));
0043        if (op == NULL) {
0044            return PyErr_NoMemory();
0045        }
0046
0047        PyObject_Init(op, &YourTypeStruct);
0048
0049        op->ob_field = value;
0050        ...
0051        return op;
0052    }
0053
0054    Note that in C++, the use of the new operator usually implies that
0055    the 1st step is performed automatically for you, so in a C++ class
0056    constructor you would start directly with PyObject_Init/InitVar. */
0057
0058
0059 typedef struct {
0060     /* user context passed as the first argument to the 2 functions */
0061     void *ctx;
0062
0063     /* allocate an arena of size bytes */
0064     void* (*alloc) (void *ctx, size_t size);
0065
0066     /* free an arena */
0067     void (*free) (void *ctx, void *ptr, size_t size);
0068 } PyObjectArenaAllocator;
0069
0070 /* Get the arena allocator. */
0071 PyAPI_FUNC(void) PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator);
0072
0073 /* Set the arena allocator. */
0074 PyAPI_FUNC(void) PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator);
0075
0076
0077 /* Test if an object implements the garbage collector protocol */
0078 PyAPI_FUNC(int) PyObject_IS_GC(PyObject *obj);
0079
0080
0081 // Test if a type supports weak references
0082 PyAPI_FUNC(int) PyType_SUPPORTS_WEAKREFS(PyTypeObject *type);
0083
0084 PyAPI_FUNC(PyObject **) PyObject_GET_WEAKREFS_LISTPTR(PyObject *op);
0085
0086 PyAPI_FUNC(PyObject *) PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *,
0087                                                              size_t);
0088
0089
0090 /* Visit all live GC-capable objects, similar to gc.get_objects(None). The
0091  * supplied callback is called on every such object with the void* arg set
0092  * to the supplied arg. Returning 0 from the callback ends iteration, returning
0093  * 1 allows iteration to continue. Returning any other value may result in
0094  * undefined behaviour.
0095  *
0096  * If new objects are (de)allocated by the callback it is undefined if they
0097  * will be visited.
0098
0099  * Garbage collection is disabled during operation. Explicitly running a
0100  * collection in the callback may lead to undefined behaviour e.g. visiting the
0101  * same objects multiple times or not at all.
0102  */
0103 typedef int (*gcvisitobjects_t)(PyObject*, void*);
0104 PyAPI_FUNC(void) PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void* arg);