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 size); |
98 | PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize); |
99 | PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size); |
100 | PyAPI_FUNC(void) PyObject_Free(void *ptr); |
101 | |
102 | /* This function returns the number of allocated memory blocks, regardless of size */ |
103 | PyAPI_FUNC(Py_ssize_t) _Py_GetAllocatedBlocks(void); |
104 | |
105 | /* Macros */ |
106 | #ifdef WITH_PYMALLOC |
107 | #ifndef Py_LIMITED_API |
108 | PyAPI_FUNC(void) _PyObject_DebugMallocStats(FILE *out); |
109 | #endif /* #ifndef Py_LIMITED_API */ |
110 | #endif |
111 | |
112 | /* Macros */ |
113 | #define PyObject_MALLOC PyObject_Malloc |
114 | #define PyObject_REALLOC PyObject_Realloc |
115 | #define PyObject_FREE PyObject_Free |
116 | #define PyObject_Del PyObject_Free |
117 | #define PyObject_DEL PyObject_Free |
118 | |
119 | |
120 | /* |
121 | * Generic object allocator interface |
122 | * ================================== |
123 | */ |
124 | |
125 | /* Functions */ |
126 | PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); |
127 | PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, |
128 | PyTypeObject *, Py_ssize_t); |
129 | PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); |
130 | PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); |
131 | |
132 | #define PyObject_New(type, typeobj) \ |
133 | ( (type *) _PyObject_New(typeobj) ) |
134 | #define PyObject_NewVar(type, typeobj, n) \ |
135 | ( (type *) _PyObject_NewVar((typeobj), (n)) ) |
136 | |
137 | /* Macros trading binary compatibility for speed. See also pymem.h. |
138 | Note that these macros expect non-NULL object pointers.*/ |
139 | #define PyObject_INIT(op, typeobj) \ |
140 | ( Py_TYPE(op) = (typeobj), _Py_NewReference((PyObject *)(op)), (op) ) |
141 | #define PyObject_INIT_VAR(op, typeobj, size) \ |
142 | ( Py_SIZE(op) = (size), PyObject_INIT((op), (typeobj)) ) |
143 | |
144 | #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) |
145 | |
146 | /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a |
147 | vrbl-size object with nitems items, exclusive of gc overhead (if any). The |
148 | value is rounded up to the closest multiple of sizeof(void *), in order to |
149 | ensure that pointer fields at the end of the object are correctly aligned |
150 | for the platform (this is of special importance for subclasses of, e.g., |
151 | str or int, so that pointers can be stored after the embedded data). |
152 | |
153 | Note that there's no memory wastage in doing this, as malloc has to |
154 | return (at worst) pointer-aligned memory anyway. |
155 | */ |
156 | #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0 |
157 | # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2" |
158 | #endif |
159 | |
160 | #define _PyObject_VAR_SIZE(typeobj, nitems) \ |
161 | _Py_SIZE_ROUND_UP((typeobj)->tp_basicsize + \ |
162 | (nitems)*(typeobj)->tp_itemsize, \ |
163 | SIZEOF_VOID_P) |
164 | |
165 | #define PyObject_NEW(type, typeobj) \ |
166 | ( (type *) PyObject_Init( \ |
167 | (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) |
168 | |
169 | #define PyObject_NEW_VAR(type, typeobj, n) \ |
170 | ( (type *) PyObject_InitVar( \ |
171 | (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\ |
172 | (typeobj), (n)) ) |
173 | |
174 | /* This example code implements an object constructor with a custom |
175 | allocator, where PyObject_New is inlined, and shows the important |
176 | distinction between two steps (at least): |
177 | 1) the actual allocation of the object storage; |
178 | 2) the initialization of the Python specific fields |
179 | in this storage with PyObject_{Init, InitVar}. |
180 | |
181 | PyObject * |
182 | YourObject_New(...) |
183 | { |
184 | PyObject *op; |
185 | |
186 | op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); |
187 | if (op == NULL) |
188 | return PyErr_NoMemory(); |
189 | |
190 | PyObject_Init(op, &YourTypeStruct); |
191 | |
192 | op->ob_field = value; |
193 | ... |
194 | return op; |
195 | } |
196 | |
197 | Note that in C++, the use of the new operator usually implies that |
198 | the 1st step is performed automatically for you, so in a C++ class |
199 | constructor you would start directly with PyObject_Init/InitVar |
200 | */ |
201 | |
202 | #ifndef Py_LIMITED_API |
203 | typedef struct { |
204 | /* user context passed as the first argument to the 2 functions */ |
205 | void *ctx; |
206 | |
207 | /* allocate an arena of size bytes */ |
208 | void* (*alloc) (void *ctx, size_t size); |
209 | |
210 | /* free an arena */ |
211 | void (*free) (void *ctx, void *ptr, size_t size); |
212 | } PyObjectArenaAllocator; |
213 | |
214 | /* Get the arena allocator. */ |
215 | PyAPI_FUNC(void) PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator); |
216 | |
217 | /* Set the arena allocator. */ |
218 | PyAPI_FUNC(void) PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator); |
219 | #endif |
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 | #ifndef Py_LIMITED_API |
231 | PyAPI_FUNC(Py_ssize_t) _PyGC_CollectNoFail(void); |
232 | #endif |
233 | |
234 | /* Test if a type has a GC head */ |
235 | #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) |
236 | |
237 | /* Test if an object has a GC head */ |
238 | #define PyObject_IS_GC(o) (PyType_IS_GC(Py_TYPE(o)) && \ |
239 | (Py_TYPE(o)->tp_is_gc == NULL || Py_TYPE(o)->tp_is_gc(o))) |
240 | |
241 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t); |
242 | #define PyObject_GC_Resize(type, op, n) \ |
243 | ( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) ) |
244 | |
245 | /* GC information is stored BEFORE the object structure. */ |
246 | #ifndef Py_LIMITED_API |
247 | typedef union _gc_head { |
248 | struct { |
249 | union _gc_head *gc_next; |
250 | union _gc_head *gc_prev; |
251 | Py_ssize_t gc_refs; |
252 | } gc; |
253 | double dummy; /* force worst-case alignment */ |
254 | } PyGC_Head; |
255 | |
256 | extern PyGC_Head *_PyGC_generation0; |
257 | |
258 | #define _Py_AS_GC(o) ((PyGC_Head *)(o)-1) |
259 | |
260 | /* Bit 0 is set when tp_finalize is called */ |
261 | #define _PyGC_REFS_MASK_FINALIZED (1 << 0) |
262 | /* The (N-1) most significant bits contain the gc state / refcount */ |
263 | #define _PyGC_REFS_SHIFT (1) |
264 | #define _PyGC_REFS_MASK (((size_t) -1) << _PyGC_REFS_SHIFT) |
265 | |
266 | #define _PyGCHead_REFS(g) ((g)->gc.gc_refs >> _PyGC_REFS_SHIFT) |
267 | #define _PyGCHead_SET_REFS(g, v) do { \ |
268 | (g)->gc.gc_refs = ((g)->gc.gc_refs & ~_PyGC_REFS_MASK) \ |
269 | | (((size_t)(v)) << _PyGC_REFS_SHIFT); \ |
270 | } while (0) |
271 | #define _PyGCHead_DECREF(g) ((g)->gc.gc_refs -= 1 << _PyGC_REFS_SHIFT) |
272 | |
273 | #define _PyGCHead_FINALIZED(g) (((g)->gc.gc_refs & _PyGC_REFS_MASK_FINALIZED) != 0) |
274 | #define _PyGCHead_SET_FINALIZED(g, v) do { \ |
275 | (g)->gc.gc_refs = ((g)->gc.gc_refs & ~_PyGC_REFS_MASK_FINALIZED) \ |
276 | | (v != 0); \ |
277 | } while (0) |
278 | |
279 | #define _PyGC_FINALIZED(o) _PyGCHead_FINALIZED(_Py_AS_GC(o)) |
280 | #define _PyGC_SET_FINALIZED(o, v) _PyGCHead_SET_FINALIZED(_Py_AS_GC(o), v) |
281 | |
282 | #define _PyGC_REFS(o) _PyGCHead_REFS(_Py_AS_GC(o)) |
283 | |
284 | #define _PyGC_REFS_UNTRACKED (-2) |
285 | #define _PyGC_REFS_REACHABLE (-3) |
286 | #define _PyGC_REFS_TENTATIVELY_UNREACHABLE (-4) |
287 | |
288 | /* Tell the GC to track this object. NB: While the object is tracked the |
289 | * collector it must be safe to call the ob_traverse method. */ |
290 | #define _PyObject_GC_TRACK(o) do { \ |
291 | PyGC_Head *g = _Py_AS_GC(o); \ |
292 | if (_PyGCHead_REFS(g) != _PyGC_REFS_UNTRACKED) \ |
293 | Py_FatalError("GC object already tracked"); \ |
294 | _PyGCHead_SET_REFS(g, _PyGC_REFS_REACHABLE); \ |
295 | g->gc.gc_next = _PyGC_generation0; \ |
296 | g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \ |
297 | g->gc.gc_prev->gc.gc_next = g; \ |
298 | _PyGC_generation0->gc.gc_prev = g; \ |
299 | } while (0); |
300 | |
301 | /* Tell the GC to stop tracking this object. |
302 | * gc_next doesn't need to be set to NULL, but doing so is a good |
303 | * way to provoke memory errors if calling code is confused. |
304 | */ |
305 | #define _PyObject_GC_UNTRACK(o) do { \ |
306 | PyGC_Head *g = _Py_AS_GC(o); \ |
307 | assert(_PyGCHead_REFS(g) != _PyGC_REFS_UNTRACKED); \ |
308 | _PyGCHead_SET_REFS(g, _PyGC_REFS_UNTRACKED); \ |
309 | g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \ |
310 | g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \ |
311 | g->gc.gc_next = NULL; \ |
312 | } while (0); |
313 | |
314 | /* True if the object is currently tracked by the GC. */ |
315 | #define _PyObject_GC_IS_TRACKED(o) \ |
316 | (_PyGC_REFS(o) != _PyGC_REFS_UNTRACKED) |
317 | |
318 | /* True if the object may be tracked by the GC in the future, or already is. |
319 | This can be useful to implement some optimizations. */ |
320 | #define _PyObject_GC_MAY_BE_TRACKED(obj) \ |
321 | (PyObject_IS_GC(obj) && \ |
322 | (!PyTuple_CheckExact(obj) || _PyObject_GC_IS_TRACKED(obj))) |
323 | #endif /* Py_LIMITED_API */ |
324 | |
325 | PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t size); |
326 | PyAPI_FUNC(PyObject *) _PyObject_GC_Calloc(size_t size); |
327 | PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); |
328 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); |
329 | PyAPI_FUNC(void) PyObject_GC_Track(void *); |
330 | PyAPI_FUNC(void) PyObject_GC_UnTrack(void *); |
331 | PyAPI_FUNC(void) PyObject_GC_Del(void *); |
332 | |
333 | #define PyObject_GC_New(type, typeobj) \ |
334 | ( (type *) _PyObject_GC_New(typeobj) ) |
335 | #define PyObject_GC_NewVar(type, typeobj, n) \ |
336 | ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) |
337 | |
338 | |
339 | /* Utility macro to help write tp_traverse functions. |
340 | * To use this macro, the tp_traverse function must name its arguments |
341 | * "visit" and "arg". This is intended to keep tp_traverse functions |
342 | * looking as much alike as possible. |
343 | */ |
344 | #define Py_VISIT(op) \ |
345 | do { \ |
346 | if (op) { \ |
347 | int vret = visit((PyObject *)(op), arg); \ |
348 | if (vret) \ |
349 | return vret; \ |
350 | } \ |
351 | } while (0) |
352 | |
353 | |
354 | /* Test if a type supports weak references */ |
355 | #define PyType_SUPPORTS_WEAKREFS(t) ((t)->tp_weaklistoffset > 0) |
356 | |
357 | #define PyObject_GET_WEAKREFS_LISTPTR(o) \ |
358 | ((PyObject **) (((char *) (o)) + Py_TYPE(o)->tp_weaklistoffset)) |
359 | |
360 | #ifdef __cplusplus |
361 | } |
362 | #endif |
363 | #endif /* !Py_OBJIMPL_H */ |
364 | |