1 /* The PyObject_ memory family:  high-level object memory interfaces.

     2    See pymem.h for the low-level PyMem_ family.

     3 */

     4 

     5 #ifndef Py_OBJIMPL_H

     6 #define Py_OBJIMPL_H

     7 

     8 #include "pymem.h"

     9 

    10 #ifdef __cplusplus

    11 extern "C" {

    12 #endif

    13 

    14 /* BEWARE:

    15 

    16    Each interface exports both functions and macros.  Extension modules should

    17    use the functions, to ensure binary compatibility across Python versions.

    18    Because the Python implementation is free to change internal details, and

    19    the macros may (or may not) expose details for speed, if you do use the

    20    macros you must recompile your extensions with each Python release.

    21 

    22    Never mix calls to PyObject_ memory functions with calls to the platform

    23    malloc/realloc/ calloc/free, or with calls to PyMem_.

    24 */

    25 

    26 /*

    27 Functions and macros for modules that implement new object types.

    28 

    29  - PyObject_New(type, typeobj) allocates memory for a new object of the given

    30    type, and initializes part of it.  'type' must be the C structure type used

    31    to represent the object, and 'typeobj' the address of the corresponding

    32    type object.  Reference count and type pointer are filled in; the rest of

    33    the bytes of the object are *undefined*!  The resulting expression type is

    34    'type *'.  The size of the object is determined by the tp_basicsize field

    35    of the type object.

    36 

    37  - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size

    38    object with room for n items.  In addition to the refcount and type pointer

    39    fields, this also fills in the ob_size field.

    40 

    41  - PyObject_Del(op) releases the memory allocated for an object.  It does not

    42    run a destructor -- it only frees the memory.  PyObject_Free is identical.

    43 

    44  - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't

    45    allocate memory.  Instead of a 'type' parameter, they take a pointer to a

    46    new object (allocated by an arbitrary allocator), and initialize its object

    47    header fields.

    48 

    49 Note that objects created with PyObject_{New, NewVar} are allocated using the

    50 specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is

    51 enabled.  In addition, a special debugging allocator is used if PYMALLOC_DEBUG

    52 is also #defined.

    53 

    54 In case a specific form of memory management is needed (for example, if you

    55 must use the platform malloc heap(s), or shared memory, or C++ local storage or

    56 operator new), you must first allocate the object with your custom allocator,

    57 then pass its pointer to PyObject_{Init, InitVar} for filling in its Python-

    58 specific fields:  reference count, type pointer, possibly others.  You should

    59 be aware that Python no control over these objects because they don't

    60 cooperate with the Python memory manager.  Such objects may not be eligible

    61 for automatic garbage collection and you have to make sure that they are

    62 released accordingly whenever their destructor gets called (cf. the specific

    63 form of memory management you're using).

    64 

    65 Unless you have specific memory management requirements, use

    66 PyObject_{New, NewVar, Del}.

    67 */

    68 

    69 /*

    70  * Raw object memory interface

    71  * ===========================

    72  */

    73 

    74 /* Functions to call the same malloc/realloc/free as used by Python's

    75    object allocator.  If WITH_PYMALLOC is enabled, these may differ from

    76    the platform malloc/realloc/free.  The Python object allocator is

    77    designed for fast, cache-conscious allocation of many "small" objects,

    78    and with low hidden memory overhead.

    79 

    80    PyObject_Malloc(0) returns a unique non-NULL pointer if possible.

    81 

    82    PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n).

    83    PyObject_Realloc(p != NULL, 0) does not return  NULL, or free the memory

    84    at p.

    85 

    86    Returned pointers must be checked for NULL explicitly; no action is

    87    performed on failure other than to return NULL (no warning it printed, no

    88    exception is set, etc).

    89 

    90    For allocating objects, use PyObject_{New, NewVar} instead whenever

    91    possible.  The PyObject_{Malloc, Realloc, Free} family is exposed

    92    so that you can exploit Python's small-block allocator for non-object

    93    uses.  If you must use these routines to allocate object memory, make sure

    94    the object gets initialized via PyObject_{Init, InitVar} after obtaining

    95    the raw memory.

    96 */

    97 PyAPI_FUNC(void *) PyObject_Malloc(size_t);

    98 PyAPI_FUNC(void *) PyObject_Realloc(void *, size_t);

    99 PyAPI_FUNC(void) PyObject_Free(void *);

   100 

   101 

   102 /* Macros */

   103 #ifdef WITH_PYMALLOC

   104 #ifdef PYMALLOC_DEBUG	/* WITH_PYMALLOC && PYMALLOC_DEBUG */

   105 PyAPI_FUNC(void *) _PyObject_DebugMalloc(size_t nbytes);

   106 PyAPI_FUNC(void *) _PyObject_DebugRealloc(void *p, size_t nbytes);

   107 PyAPI_FUNC(void) _PyObject_DebugFree(void *p);

   108 PyAPI_FUNC(void) _PyObject_DebugDumpAddress(const void *p);

   109 PyAPI_FUNC(void) _PyObject_DebugCheckAddress(const void *p);

   110 PyAPI_FUNC(void) _PyObject_DebugMallocStats(void);

   111 #define PyObject_MALLOC		_PyObject_DebugMalloc

   112 #define PyObject_Malloc		_PyObject_DebugMalloc

   113 #define PyObject_REALLOC	_PyObject_DebugRealloc

   114 #define PyObject_Realloc	_PyObject_DebugRealloc

   115 #define PyObject_FREE		_PyObject_DebugFree

   116 #define PyObject_Free		_PyObject_DebugFree

   117 

   118 #else	/* WITH_PYMALLOC && ! PYMALLOC_DEBUG */

   119 #define PyObject_MALLOC		PyObject_Malloc

   120 #define PyObject_REALLOC	PyObject_Realloc

   121 #define PyObject_FREE		PyObject_Free

   122 #endif

   123 

   124 #else	/* ! WITH_PYMALLOC */

   125 #define PyObject_MALLOC		PyMem_MALLOC

   126 #define PyObject_REALLOC	PyMem_REALLOC

   127 #define PyObject_FREE		PyMem_FREE

   128 

   129 #endif	/* WITH_PYMALLOC */

   130 

   131 #define PyObject_Del		PyObject_Free

   132 #define PyObject_DEL		PyObject_FREE

   133 

   134 /* for source compatibility with 2.2 */

   135 #define _PyObject_Del		PyObject_Free

   136 

   137 /*

   138  * Generic object allocator interface

   139  * ==================================

   140  */

   141 

   142 /* Functions */

   143 PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *);

   144 PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *,

   145                                                  PyTypeObject *, Py_ssize_t);

   146 PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *);

   147 PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t);

   148 

   149 #define PyObject_New(type, typeobj) \

   150 		( (type *) _PyObject_New(typeobj) )

   151 #define PyObject_NewVar(type, typeobj, n) \

   152 		( (type *) _PyObject_NewVar((typeobj), (n)) )

   153 

   154 /* Macros trading binary compatibility for speed. See also pymem.h.

   155    Note that these macros expect non-NULL object pointers.*/

   156 #define PyObject_INIT(op, typeobj) \

   157 	( Py_TYPE(op) = (typeobj), _Py_NewReference((PyObject *)(op)), (op) )

   158 #define PyObject_INIT_VAR(op, typeobj, size) \

   159 	( Py_SIZE(op) = (size), PyObject_INIT((op), (typeobj)) )

   160 

   161 #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize )

   162 

   163 /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a

   164    vrbl-size object with nitems items, exclusive of gc overhead (if any).  The

   165    value is rounded up to the closest multiple of sizeof(void *), in order to

   166    ensure that pointer fields at the end of the object are correctly aligned

   167    for the platform (this is of special importance for subclasses of, e.g.,

   168    str or long, so that pointers can be stored after the embedded data).

   169 

   170    Note that there's no memory wastage in doing this, as malloc has to

   171    return (at worst) pointer-aligned memory anyway.

   172 */

   173 #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0

   174 #   error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2"

   175 #endif

   176 

   177 #define _PyObject_VAR_SIZE(typeobj, nitems)	\

   178 	(size_t)				\

   179 	( ( (typeobj)->tp_basicsize +		\

   180 	    (nitems)*(typeobj)->tp_itemsize +	\

   181 	    (SIZEOF_VOID_P - 1)			\

   182 	  ) & ~(SIZEOF_VOID_P - 1)		\

   183 	)

   184 

   185 #define PyObject_NEW(type, typeobj) \

   186 ( (type *) PyObject_Init( \

   187 	(PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) )

   188 

   189 #define PyObject_NEW_VAR(type, typeobj, n) \

   190 ( (type *) PyObject_InitVar( \

   191       (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\

   192       (typeobj), (n)) )

   193 

   194 /* This example code implements an object constructor with a custom

   195    allocator, where PyObject_New is inlined, and shows the important

   196    distinction between two steps (at least):

   197        1) the actual allocation of the object storage;

   198        2) the initialization of the Python specific fields

   199           in this storage with PyObject_{Init, InitVar}.

   200 

   201    PyObject *

   202    YourObject_New(...)

   203    {

   204        PyObject *op;

   205 

   206        op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct));

   207        if (op == NULL)

   208            return PyErr_NoMemory();

   209 

   210        PyObject_Init(op, &YourTypeStruct);

   211 

   212        op->ob_field = value;

   213        ...

   214        return op;

   215    }

   216 

   217    Note that in C++, the use of the new operator usually implies that

   218    the 1st step is performed automatically for you, so in a C++ class

   219    constructor you would start directly with PyObject_Init/InitVar

   220 */

   221 

   222 /*

   223  * Garbage Collection Support

   224  * ==========================

   225  */

   226 

   227 /* C equivalent of gc.collect(). */

   228 PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void);

   229 

   230 /* Test if a type has a GC head */

   231 #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)

   232 

   233 /* Test if an object has a GC head */

   234 #define PyObject_IS_GC(o) (PyType_IS_GC(Py_TYPE(o)) && \

   235 	(Py_TYPE(o)->tp_is_gc == NULL || Py_TYPE(o)->tp_is_gc(o)))

   236 

   237 PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t);

   238 #define PyObject_GC_Resize(type, op, n) \

   239 		( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) )

   240 

   241 /* for source compatibility with 2.2 */

   242 #define _PyObject_GC_Del PyObject_GC_Del

   243 

   244 /* GC information is stored BEFORE the object structure. */

   245 typedef union _gc_head {

   246 	struct {

   247 		union _gc_head *gc_next;

   248 		union _gc_head *gc_prev;

   249 		Py_ssize_t gc_refs;

   250 	} gc;

   251 	long double dummy;  /* force worst-case alignment */

   252 } PyGC_Head;

   253 

   254 extern PyGC_Head *_PyGC_generation0;

   255 

   256 #define _Py_AS_GC(o) ((PyGC_Head *)(o)-1)

   257 

   258 #define _PyGC_REFS_UNTRACKED			(-2)

   259 #define _PyGC_REFS_REACHABLE			(-3)

   260 #define _PyGC_REFS_TENTATIVELY_UNREACHABLE	(-4)

   261 

   262 /* Tell the GC to track this object.  NB: While the object is tracked the

   263  * collector it must be safe to call the ob_traverse method. */

   264 #define _PyObject_GC_TRACK(o) do { \

   265 	PyGC_Head *g = _Py_AS_GC(o); \

   266 	if (g->gc.gc_refs != _PyGC_REFS_UNTRACKED) \

   267 		Py_FatalError("GC object already tracked"); \

   268 	g->gc.gc_refs = _PyGC_REFS_REACHABLE; \

   269 	g->gc.gc_next = _PyGC_generation0; \

   270 	g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \

   271 	g->gc.gc_prev->gc.gc_next = g; \

   272 	_PyGC_generation0->gc.gc_prev = g; \

   273     } while (0);

   274 

   275 /* Tell the GC to stop tracking this object.

   276  * gc_next doesn't need to be set to NULL, but doing so is a good

   277  * way to provoke memory errors if calling code is confused.

   278  */

   279 #define _PyObject_GC_UNTRACK(o) do { \

   280 	PyGC_Head *g = _Py_AS_GC(o); \

   281 	assert(g->gc.gc_refs != _PyGC_REFS_UNTRACKED); \

   282 	g->gc.gc_refs = _PyGC_REFS_UNTRACKED; \

   283 	g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \

   284 	g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \

   285 	g->gc.gc_next = NULL; \

   286     } while (0);

   287 

   288 PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t);

   289 PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *);

   290 PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t);

   291 PyAPI_FUNC(void) PyObject_GC_Track(void *);

   292 PyAPI_FUNC(void) PyObject_GC_UnTrack(void *);

   293 PyAPI_FUNC(void) PyObject_GC_Del(void *);

   294 

   295 #define PyObject_GC_New(type, typeobj) \

   296 		( (type *) _PyObject_GC_New(typeobj) )

   297 #define PyObject_GC_NewVar(type, typeobj, n) \

   298 		( (type *) _PyObject_GC_NewVar((typeobj), (n)) )

   299 

   300 

   301 /* Utility macro to help write tp_traverse functions.

   302  * To use this macro, the tp_traverse function must name its arguments

   303  * "visit" and "arg".  This is intended to keep tp_traverse functions

   304  * looking as much alike as possible.

   305  */

   306 #define Py_VISIT(op)							\

   307         do { 								\

   308                 if (op) {						\

   309                         int vret = visit((PyObject *)(op), arg);	\

   310                         if (vret)					\

   311                                 return vret;				\

   312                 }							\

   313         } while (0)

   314 

   315 /* This is here for the sake of backwards compatibility.  Extensions that

   316  * use the old GC API will still compile but the objects will not be

   317  * tracked by the GC. */

   318 #define PyGC_HEAD_SIZE 0

   319 #define PyObject_GC_Init(op)

   320 #define PyObject_GC_Fini(op)

   321 #define PyObject_AS_GC(op) (op)

   322 #define PyObject_FROM_GC(op) (op)

   323 

   324 

   325 /* Test if a type supports weak references */

   326 #define PyType_SUPPORTS_WEAKREFS(t) \

   327         (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \

   328          && ((t)->tp_weaklistoffset > 0))

   329 

   330 #define PyObject_GET_WEAKREFS_LISTPTR(o) \

   331 	((PyObject **) (((char *) (o)) + Py_TYPE(o)->tp_weaklistoffset))

   332 

   333 #ifdef __cplusplus

   334 }

   335 #endif

   336 #endif /* !Py_OBJIMPL_H */