Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 1 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 2 | #ifndef Py_OBJIMPL_H |
| 3 | #define Py_OBJIMPL_H |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 4 | |
| 5 | #include "pymem.h" |
| 6 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 7 | #ifdef __cplusplus |
| 8 | extern "C" { |
| 9 | #endif |
| 10 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 11 | /* |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 12 | Functions and macros for modules that implement new object types. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 13 | You must first include "object.h". |
| 14 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 15 | - PyObject_New(type, typeobj) allocates memory for a new object of |
| 16 | the given type; here 'type' must be the C structure type used to |
| 17 | represent the object and 'typeobj' the address of the corresponding |
| 18 | type object. Reference count and type pointer are filled in; the |
| 19 | rest of the bytes of the object are *undefined*! The resulting |
| 20 | expression type is 'type *'. The size of the object is actually |
| 21 | determined by the tp_basicsize field of the type object. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 22 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 23 | - PyObject_NewVar(type, typeobj, n) is similar but allocates a |
| 24 | variable-size object with n extra items. The size is computed as |
| 25 | tp_basicsize plus n * tp_itemsize. This fills in the ob_size field |
| 26 | as well. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 27 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 28 | - PyObject_Del(op) releases the memory allocated for an object. |
| 29 | |
| 30 | - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) are |
| 31 | similar to PyObject_{New, NewVar} except that they don't allocate |
| 32 | the memory needed for an object. Instead of the 'type' parameter, |
| 33 | they accept the pointer of a new object (allocated by an arbitrary |
| 34 | allocator) and initialize its object header fields. |
| 35 | |
| 36 | Note that objects created with PyObject_{New, NewVar} are allocated |
| 37 | within the Python heap by an object allocator, the latter being |
| 38 | implemented (by default) on top of the Python raw memory |
| 39 | allocator. This ensures that Python keeps control on the user's |
| 40 | objects regarding their memory management; for instance, they may be |
| 41 | subject to automatic garbage collection. |
| 42 | |
| 43 | In case a specific form of memory management is needed, implying that |
| 44 | the objects would not reside in the Python heap (for example standard |
| 45 | malloc heap(s) are mandatory, use of shared memory, C++ local storage |
| 46 | or operator new), you must first allocate the object with your custom |
| 47 | allocator, then pass its pointer to PyObject_{Init, InitVar} for |
| 48 | filling in its Python-specific fields: reference count, type pointer, |
| 49 | possibly others. You should be aware that Python has very limited |
| 50 | control over these objects because they don't cooperate with the |
| 51 | Python memory manager. Such objects may not be eligible for automatic |
| 52 | garbage collection and you have to make sure that they are released |
| 53 | accordingly whenever their destructor gets called (cf. the specific |
| 54 | form of memory management you're using). |
| 55 | |
| 56 | Unless you have specific memory management requirements, it is |
| 57 | recommended to use PyObject_{New, NewVar, Del}. */ |
| 58 | |
| 59 | /* |
| 60 | * Core object memory allocator |
| 61 | * ============================ |
| 62 | */ |
| 63 | |
Vladimir Marangozov | d8a9332 | 2000-07-10 04:30:56 +0000 | [diff] [blame] | 64 | /* The purpose of the object allocator is to make the distinction |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 65 | between "object memory" and the rest within the Python heap. |
| 66 | |
| 67 | Object memory is the one allocated by PyObject_{New, NewVar}, i.e. |
| 68 | the one that holds the object's representation defined by its C |
| 69 | type structure, *excluding* any object-specific memory buffers that |
| 70 | might be referenced by the structure (for type structures that have |
| 71 | pointer fields). By default, the object memory allocator is |
| 72 | implemented on top of the raw memory allocator. |
| 73 | |
| 74 | The PyCore_* macros can be defined to make the interpreter use a |
| 75 | custom object memory allocator. They are reserved for internal |
| 76 | memory management purposes exclusively. Both the core and extension |
| 77 | modules should use the PyObject_* API. */ |
| 78 | |
Neil Schemenauer | a35c688 | 2001-02-27 04:45:05 +0000 | [diff] [blame] | 79 | #ifdef WITH_PYMALLOC |
| 80 | #define PyCore_OBJECT_MALLOC_FUNC _PyCore_ObjectMalloc |
| 81 | #define PyCore_OBJECT_REALLOC_FUNC _PyCore_ObjectRealloc |
| 82 | #define PyCore_OBJECT_FREE_FUNC _PyCore_ObjectFree |
| 83 | #define NEED_TO_DECLARE_OBJECT_MALLOC_AND_FRIEND |
| 84 | #endif /* !WITH_PYMALLOC */ |
| 85 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 86 | #ifndef PyCore_OBJECT_MALLOC_FUNC |
| 87 | #undef PyCore_OBJECT_REALLOC_FUNC |
| 88 | #undef PyCore_OBJECT_FREE_FUNC |
| 89 | #define PyCore_OBJECT_MALLOC_FUNC PyCore_MALLOC_FUNC |
| 90 | #define PyCore_OBJECT_REALLOC_FUNC PyCore_REALLOC_FUNC |
| 91 | #define PyCore_OBJECT_FREE_FUNC PyCore_FREE_FUNC |
| 92 | #endif |
| 93 | |
| 94 | #ifndef PyCore_OBJECT_MALLOC_PROTO |
| 95 | #undef PyCore_OBJECT_REALLOC_PROTO |
| 96 | #undef PyCore_OBJECT_FREE_PROTO |
| 97 | #define PyCore_OBJECT_MALLOC_PROTO PyCore_MALLOC_PROTO |
| 98 | #define PyCore_OBJECT_REALLOC_PROTO PyCore_REALLOC_PROTO |
| 99 | #define PyCore_OBJECT_FREE_PROTO PyCore_FREE_PROTO |
| 100 | #endif |
| 101 | |
| 102 | #ifdef NEED_TO_DECLARE_OBJECT_MALLOC_AND_FRIEND |
Thomas Wouters | 334fb89 | 2000-07-25 12:56:38 +0000 | [diff] [blame] | 103 | extern void *PyCore_OBJECT_MALLOC_FUNC PyCore_OBJECT_MALLOC_PROTO; |
| 104 | extern void *PyCore_OBJECT_REALLOC_FUNC PyCore_OBJECT_REALLOC_PROTO; |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 105 | extern void PyCore_OBJECT_FREE_FUNC PyCore_OBJECT_FREE_PROTO; |
| 106 | #endif |
| 107 | |
| 108 | #ifndef PyCore_OBJECT_MALLOC |
| 109 | #undef PyCore_OBJECT_REALLOC |
| 110 | #undef PyCore_OBJECT_FREE |
| 111 | #define PyCore_OBJECT_MALLOC(n) PyCore_OBJECT_MALLOC_FUNC(n) |
| 112 | #define PyCore_OBJECT_REALLOC(p, n) PyCore_OBJECT_REALLOC_FUNC((p), (n)) |
| 113 | #define PyCore_OBJECT_FREE(p) PyCore_OBJECT_FREE_FUNC(p) |
| 114 | #endif |
| 115 | |
| 116 | /* |
| 117 | * Raw object memory interface |
| 118 | * =========================== |
| 119 | */ |
| 120 | |
| 121 | /* The use of this API should be avoided, unless a builtin object |
| 122 | constructor inlines PyObject_{New, NewVar}, either because the |
| 123 | latter functions cannot allocate the exact amount of needed memory, |
| 124 | either for speed. This situation is exceptional, but occurs for |
| 125 | some object constructors (PyBuffer_New, PyList_New...). Inlining |
| 126 | PyObject_{New, NewVar} for objects that are supposed to belong to |
| 127 | the Python heap is discouraged. If you really have to, make sure |
| 128 | the object is initialized with PyObject_{Init, InitVar}. Do *not* |
| 129 | inline PyObject_{Init, InitVar} for user-extension types or you |
| 130 | might seriously interfere with Python's memory management. */ |
| 131 | |
| 132 | /* Functions */ |
| 133 | |
| 134 | /* Wrappers around PyCore_OBJECT_MALLOC and friends; useful if you |
| 135 | need to be sure that you are using the same object memory allocator |
| 136 | as Python. These wrappers *do not* make sure that allocating 0 |
| 137 | bytes returns a non-NULL pointer. Returned pointers must be checked |
| 138 | for NULL explicitly; no action is performed on failure. */ |
Thomas Wouters | 334fb89 | 2000-07-25 12:56:38 +0000 | [diff] [blame] | 139 | extern DL_IMPORT(void *) PyObject_Malloc(size_t); |
| 140 | extern DL_IMPORT(void *) PyObject_Realloc(void *, size_t); |
| 141 | extern DL_IMPORT(void) PyObject_Free(void *); |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 142 | |
| 143 | /* Macros */ |
| 144 | #define PyObject_MALLOC(n) PyCore_OBJECT_MALLOC(n) |
Thomas Wouters | 334fb89 | 2000-07-25 12:56:38 +0000 | [diff] [blame] | 145 | #define PyObject_REALLOC(op, n) PyCore_OBJECT_REALLOC((void *)(op), (n)) |
| 146 | #define PyObject_FREE(op) PyCore_OBJECT_FREE((void *)(op)) |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 147 | |
| 148 | /* |
| 149 | * Generic object allocator interface |
| 150 | * ================================== |
| 151 | */ |
| 152 | |
| 153 | /* Functions */ |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 154 | extern DL_IMPORT(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); |
| 155 | extern DL_IMPORT(PyVarObject *) PyObject_InitVar(PyVarObject *, |
| 156 | PyTypeObject *, int); |
| 157 | extern DL_IMPORT(PyObject *) _PyObject_New(PyTypeObject *); |
| 158 | extern DL_IMPORT(PyVarObject *) _PyObject_NewVar(PyTypeObject *, int); |
| 159 | extern DL_IMPORT(void) _PyObject_Del(PyObject *); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 160 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 161 | #define PyObject_New(type, typeobj) \ |
| 162 | ( (type *) _PyObject_New(typeobj) ) |
| 163 | #define PyObject_NewVar(type, typeobj, n) \ |
| 164 | ( (type *) _PyObject_NewVar((typeobj), (n)) ) |
| 165 | #define PyObject_Del(op) _PyObject_Del((PyObject *)(op)) |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 166 | |
Andrew M. Kuchling | 1582a3a | 2000-08-16 12:27:23 +0000 | [diff] [blame] | 167 | /* Macros trading binary compatibility for speed. See also pymem.h. |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 168 | Note that these macros expect non-NULL object pointers.*/ |
| 169 | #define PyObject_INIT(op, typeobj) \ |
Fred Drake | 4e262a9 | 2001-03-22 18:26:47 +0000 | [diff] [blame^] | 170 | ( (op)->ob_type = (typeobj), _Py_NewReference((PyObject *)(op)), (op) ) |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 171 | #define PyObject_INIT_VAR(op, typeobj, size) \ |
| 172 | ( (op)->ob_size = (size), PyObject_INIT((op), (typeobj)) ) |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 173 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 174 | #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) |
| 175 | #define _PyObject_VAR_SIZE(typeobj, n) \ |
| 176 | ( (typeobj)->tp_basicsize + (n) * (typeobj)->tp_itemsize ) |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 177 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 178 | #define PyObject_NEW(type, typeobj) \ |
| 179 | ( (type *) PyObject_Init( \ |
| 180 | (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) |
| 181 | #define PyObject_NEW_VAR(type, typeobj, n) \ |
| 182 | ( (type *) PyObject_InitVar( \ |
| 183 | (PyVarObject *) PyObject_MALLOC( _PyObject_VAR_SIZE((typeobj),(n)) ),\ |
| 184 | (typeobj), (n)) ) |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 185 | |
Guido van Rossum | 4cc6ac7 | 2000-07-01 01:00:38 +0000 | [diff] [blame] | 186 | #define PyObject_DEL(op) PyObject_FREE(op) |
| 187 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 188 | /* This example code implements an object constructor with a custom |
| 189 | allocator, where PyObject_New is inlined, and shows the important |
| 190 | distinction between two steps (at least): |
| 191 | 1) the actual allocation of the object storage; |
| 192 | 2) the initialization of the Python specific fields |
| 193 | in this storage with PyObject_{Init, InitVar}. |
| 194 | |
| 195 | PyObject * |
| 196 | YourObject_New(...) |
| 197 | { |
| 198 | PyObject *op; |
| 199 | |
| 200 | op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); |
| 201 | if (op == NULL) |
| 202 | return PyErr_NoMemory(); |
| 203 | |
| 204 | op = PyObject_Init(op, &YourTypeStruct); |
| 205 | if (op == NULL) |
| 206 | return NULL; |
| 207 | |
| 208 | op->ob_field = value; |
| 209 | ... |
| 210 | return op; |
| 211 | } |
| 212 | |
| 213 | Note that in C++, the use of the new operator usually implies that |
| 214 | the 1st step is performed automatically for you, so in a C++ class |
| 215 | constructor you would start directly with PyObject_Init/InitVar. */ |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 216 | |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 217 | /* |
| 218 | * Garbage Collection Support |
| 219 | * ========================== |
| 220 | */ |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 221 | |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 222 | /* To make a new object participate in garbage collection use |
| 223 | PyObject_{New, VarNew, Del} to manage the memory. Set the type flag |
Neil Schemenauer | a6c861f | 2001-01-20 15:50:42 +0000 | [diff] [blame] | 224 | Py_TPFLAGS_GC and define the type method tp_traverse. You should also |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 225 | add the method tp_clear if your object is mutable. Include |
Guido van Rossum | 4cc6ac7 | 2000-07-01 01:00:38 +0000 | [diff] [blame] | 226 | PyGC_HEAD_SIZE in the calculation of tp_basicsize. Call |
Neil Schemenauer | a6c861f | 2001-01-20 15:50:42 +0000 | [diff] [blame] | 227 | PyObject_GC_Init after the pointers followed by tp_traverse become |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 228 | valid (usually just before returning the object from the allocation |
| 229 | method. Call PyObject_GC_Fini before those pointers become invalid |
| 230 | (usually at the top of the deallocation method). */ |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 231 | |
| 232 | #ifndef WITH_CYCLE_GC |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 233 | |
| 234 | #define PyGC_HEAD_SIZE 0 |
| 235 | #define PyObject_GC_Init(op) |
| 236 | #define PyObject_GC_Fini(op) |
| 237 | #define PyObject_AS_GC(op) (op) |
| 238 | #define PyObject_FROM_GC(op) (op) |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 239 | |
| 240 | #else |
| 241 | |
| 242 | /* Add the object into the container set */ |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 243 | extern DL_IMPORT(void) _PyGC_Insert(PyObject *); |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 244 | |
| 245 | /* Remove the object from the container set */ |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 246 | extern DL_IMPORT(void) _PyGC_Remove(PyObject *); |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 247 | |
| 248 | #define PyObject_GC_Init(op) _PyGC_Insert((PyObject *)op) |
| 249 | #define PyObject_GC_Fini(op) _PyGC_Remove((PyObject *)op) |
| 250 | |
| 251 | /* Structure *prefixed* to container objects participating in GC */ |
| 252 | typedef struct _gc_head { |
| 253 | struct _gc_head *gc_next; |
| 254 | struct _gc_head *gc_prev; |
| 255 | int gc_refs; |
| 256 | } PyGC_Head; |
| 257 | |
| 258 | #define PyGC_HEAD_SIZE sizeof(PyGC_Head) |
| 259 | |
| 260 | /* Test if a type has a GC head */ |
| 261 | #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_GC) |
| 262 | |
| 263 | /* Test if an object has a GC head */ |
| 264 | #define PyObject_IS_GC(o) PyType_IS_GC((o)->ob_type) |
| 265 | |
| 266 | /* Get an object's GC head */ |
| 267 | #define PyObject_AS_GC(o) ((PyGC_Head *)(o)-1) |
| 268 | |
| 269 | /* Get the object given the PyGC_Head */ |
| 270 | #define PyObject_FROM_GC(g) ((PyObject *)(((PyGC_Head *)g)+1)) |
| 271 | |
Barry Warsaw | 430d773 | 2001-01-24 04:17:26 +0000 | [diff] [blame] | 272 | extern DL_IMPORT(void) _PyGC_Dump(PyGC_Head *); |
Barry Warsaw | 803eff2 | 2001-01-23 16:37:22 +0000 | [diff] [blame] | 273 | |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 274 | #endif /* WITH_CYCLE_GC */ |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 275 | |
Fred Drake | 41deb1e | 2001-02-01 05:27:45 +0000 | [diff] [blame] | 276 | /* Test if a type supports weak references */ |
Fred Drake | 033f312 | 2001-02-02 18:17:30 +0000 | [diff] [blame] | 277 | #define PyType_SUPPORTS_WEAKREFS(t) \ |
| 278 | (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \ |
| 279 | && ((t)->tp_weaklistoffset > 0)) |
Fred Drake | 41deb1e | 2001-02-01 05:27:45 +0000 | [diff] [blame] | 280 | |
| 281 | #define PyObject_GET_WEAKREFS_LISTPTR(o) \ |
| 282 | ((PyObject **) (((char *) (o)) + (o)->ob_type->tp_weaklistoffset)) |
| 283 | |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 284 | #ifdef __cplusplus |
| 285 | } |
| 286 | #endif |
| 287 | #endif /* !Py_OBJIMPL_H */ |