codekingpro/portable-devtools

1// The PyObject_ memory family:  high-level object memory interfaces.2// See pymem.h for the low-level PyMem_ family.3 4#ifndef Py_OBJIMPL_H5#define Py_OBJIMPL_H6#ifdef __cplusplus7extern "C" {8#endif9 10/* BEWARE:11 12   Each interface exports both functions and macros.  Extension modules should13   use the functions, to ensure binary compatibility across Python versions.14   Because the Python implementation is free to change internal details, and15   the macros may (or may not) expose details for speed, if you do use the16   macros you must recompile your extensions with each Python release.17 18   Never mix calls to PyObject_ memory functions with calls to the platform19   malloc/realloc/ calloc/free, or with calls to PyMem_.20*/21 22/*23Functions and macros for modules that implement new object types.24 25 - PyObject_New(type, typeobj) allocates memory for a new object of the given26   type, and initializes part of it.  'type' must be the C structure type used27   to represent the object, and 'typeobj' the address of the corresponding28   type object.  Reference count and type pointer are filled in; the rest of29   the bytes of the object are *undefined*!  The resulting expression type is30   'type *'.  The size of the object is determined by the tp_basicsize field31   of the type object.32 33 - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size34   object with room for n items.  In addition to the refcount and type pointer35   fields, this also fills in the ob_size field.36 37 - PyObject_Free(op) releases the memory allocated for an object.  It does not38   run a destructor -- it only frees the memory.39 40 - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't41   allocate memory.  Instead of a 'type' parameter, they take a pointer to a42   new object (allocated by an arbitrary allocator), and initialize its object43   header fields.44 45Note that objects created with PyObject_{New, NewVar} are allocated using the46specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is47enabled.  In addition, a special debugging allocator is used if Py_DEBUG48macro is also defined.49 50In case a specific form of memory management is needed (for example, if you51must use the platform malloc heap(s), or shared memory, or C++ local storage or52operator new), you must first allocate the object with your custom allocator,53then pass its pointer to PyObject_{Init, InitVar} for filling in its Python-54specific fields:  reference count, type pointer, possibly others.  You should55be aware that Python has no control over these objects because they don't56cooperate with the Python memory manager.  Such objects may not be eligible57for automatic garbage collection and you have to make sure that they are58released accordingly whenever their destructor gets called (cf. the specific59form of memory management you're using).60 61Unless you have specific memory management requirements, use62PyObject_{New, NewVar, Del}.63*/64 65/*66 * Raw object memory interface67 * ===========================68 */69 70/* Functions to call the same malloc/realloc/free as used by Python's71   object allocator.  If WITH_PYMALLOC is enabled, these may differ from72   the platform malloc/realloc/free.  The Python object allocator is73   designed for fast, cache-conscious allocation of many "small" objects,74   and with low hidden memory overhead.75 76   PyObject_Malloc(0) returns a unique non-NULL pointer if possible.77 78   PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n).79   PyObject_Realloc(p != NULL, 0) does not return  NULL, or free the memory80   at p.81 82   Returned pointers must be checked for NULL explicitly; no action is83   performed on failure other than to return NULL (no warning it printed, no84   exception is set, etc).85 86   For allocating objects, use PyObject_{New, NewVar} instead whenever87   possible.  The PyObject_{Malloc, Realloc, Free} family is exposed88   so that you can exploit Python's small-block allocator for non-object89   uses.  If you must use these routines to allocate object memory, make sure90   the object gets initialized via PyObject_{Init, InitVar} after obtaining91   the raw memory.92*/93PyAPI_FUNC(void *) PyObject_Malloc(size_t size);94#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x0305000095PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize);96#endif97PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size);98PyAPI_FUNC(void) PyObject_Free(void *ptr);99 100 101// Deprecated aliases only kept for backward compatibility.102// PyObject_Del and PyObject_DEL are defined with no parameter to be able to103// use them as function pointers (ex: tp_free = PyObject_Del).104#define PyObject_MALLOC         PyObject_Malloc105#define PyObject_REALLOC        PyObject_Realloc106#define PyObject_FREE           PyObject_Free107#define PyObject_Del            PyObject_Free108#define PyObject_DEL            PyObject_Free109 110 111/*112 * Generic object allocator interface113 * ==================================114 */115 116/* Functions */117PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *);118PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *,119                                           PyTypeObject *, Py_ssize_t);120 121#define PyObject_INIT(op, typeobj) \122    PyObject_Init(_PyObject_CAST(op), (typeobj))123#define PyObject_INIT_VAR(op, typeobj, size) \124    PyObject_InitVar(_PyVarObject_CAST(op), (typeobj), (size))125 126 127PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *);128PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t);129 130#define PyObject_New(type, typeobj) ((type *)_PyObject_New(typeobj))131 132// Alias to PyObject_New(). In Python 3.8, PyObject_NEW() called directly133// PyObject_MALLOC() with _PyObject_SIZE().134#define PyObject_NEW(type, typeobj) PyObject_New(type, (typeobj))135 136#define PyObject_NewVar(type, typeobj, n) \137                ( (type *) _PyObject_NewVar((typeobj), (n)) )138 139// Alias to PyObject_NewVar(). In Python 3.8, PyObject_NEW_VAR() called140// directly PyObject_MALLOC() with _PyObject_VAR_SIZE().141#define PyObject_NEW_VAR(type, typeobj, n) PyObject_NewVar(type, (typeobj), (n))142 143 144/*145 * Garbage Collection Support146 * ==========================147 */148 149/* C equivalent of gc.collect(). */150PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void);151/* C API for controlling the state of the garbage collector */152PyAPI_FUNC(int) PyGC_Enable(void);153PyAPI_FUNC(int) PyGC_Disable(void);154PyAPI_FUNC(int) PyGC_IsEnabled(void);155 156/* Test if a type has a GC head */157#define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)158 159PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t);160#define PyObject_GC_Resize(type, op, n) \161                ( (type *) _PyObject_GC_Resize(_PyVarObject_CAST(op), (n)) )162 163 164 165PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *);166PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t);167 168/* Tell the GC to track this object.169 *170 * See also private _PyObject_GC_TRACK() macro. */171PyAPI_FUNC(void) PyObject_GC_Track(void *);172 173/* Tell the GC to stop tracking this object.174 *175 * See also private _PyObject_GC_UNTRACK() macro. */176PyAPI_FUNC(void) PyObject_GC_UnTrack(void *);177 178PyAPI_FUNC(void) PyObject_GC_Del(void *);179 180#define PyObject_GC_New(type, typeobj) \181    _Py_CAST(type*, _PyObject_GC_New(typeobj))182#define PyObject_GC_NewVar(type, typeobj, n) \183    _Py_CAST(type*, _PyObject_GC_NewVar((typeobj), (n)))184 185PyAPI_FUNC(int) PyObject_GC_IsTracked(PyObject *);186PyAPI_FUNC(int) PyObject_GC_IsFinalized(PyObject *);187 188/* Utility macro to help write tp_traverse functions.189 * To use this macro, the tp_traverse function must name its arguments190 * "visit" and "arg".  This is intended to keep tp_traverse functions191 * looking as much alike as possible.192 */193#define Py_VISIT(op)                                                    \194    do {                                                                \195        if (op) {                                                       \196            int vret = visit(_PyObject_CAST(op), arg);                  \197            if (vret)                                                   \198                return vret;                                            \199        }                                                               \200    } while (0)201 202#ifndef Py_LIMITED_API203#  define Py_CPYTHON_OBJIMPL_H204#  include "cpython/objimpl.h"205#  undef Py_CPYTHON_OBJIMPL_H206#endif207 208#ifdef __cplusplus209}210#endif211#endif   // !Py_OBJIMPL_H212