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