| 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
|
|---|
|
|---|
