python3.12/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 /* Code built with Py_BUILD_CORE must include pycore_gc.h instead which
0082    defines a different _PyGC_FINALIZED() macro. */
0083 #ifndef Py_BUILD_CORE
0084    // Kept for backward compatibility with Python 3.8
0085 #  define _PyGC_FINALIZED(o) PyObject_GC_IsFinalized(o)
0086 #endif
0087
0088
0089 // Test if a type supports weak references
0090 PyAPI_FUNC(int) PyType_SUPPORTS_WEAKREFS(PyTypeObject *type);
0091
0092 PyAPI_FUNC(PyObject **) PyObject_GET_WEAKREFS_LISTPTR(PyObject *op);
0093
0094 PyAPI_FUNC(PyObject *) PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *,
0095                                                              size_t);