Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 1 | /* The PyObject_ memory family: high-level object memory interfaces. |
| 2 | See pymem.h for the low-level PyMem_ family. |
| 3 | */ |
Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 4 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 5 | #ifndef Py_OBJIMPL_H |
| 6 | #define Py_OBJIMPL_H |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 7 | |
| 8 | #include "pymem.h" |
| 9 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 10 | #ifdef __cplusplus |
| 11 | extern "C" { |
| 12 | #endif |
| 13 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 26 | /* |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 27 | Functions and macros for modules that implement new object types. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 28 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 36 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 40 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 43 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 48 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 53 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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 |
Alexey | 517da1e | 2018-02-07 02:07:30 +0300 | [diff] [blame] | 59 | be aware that Python has no control over these objects because they don't |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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 |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 63 | form of memory management you're using). |
| 64 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 65 | Unless you have specific memory management requirements, use |
| 66 | PyObject_{New, NewVar, Del}. |
| 67 | */ |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 68 | |
Tim Peters | 6d483d3 | 2001-10-06 21:27:34 +0000 | [diff] [blame] | 69 | /* |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 70 | * Raw object memory interface |
| 71 | * =========================== |
| 72 | */ |
| 73 | |
Tim Peters | e9e7452 | 2002-04-12 05:21:34 +0000 | [diff] [blame] | 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, |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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 | */ |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 97 | PyAPI_FUNC(void *) PyObject_Malloc(size_t size); |
Serhiy Storchaka | 34d0ac8 | 2016-12-27 14:57:39 +0200 | [diff] [blame] | 98 | #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 |
Victor Stinner | db067af | 2014-05-02 22:31:14 +0200 | [diff] [blame] | 99 | PyAPI_FUNC(void *) PyObject_Calloc(size_t nelem, size_t elsize); |
Serhiy Storchaka | 34d0ac8 | 2016-12-27 14:57:39 +0200 | [diff] [blame] | 100 | #endif |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 101 | PyAPI_FUNC(void *) PyObject_Realloc(void *ptr, size_t new_size); |
| 102 | PyAPI_FUNC(void) PyObject_Free(void *ptr); |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 103 | |
Serhiy Storchaka | 9fab79b | 2016-09-11 11:03:14 +0300 | [diff] [blame] | 104 | #ifndef Py_LIMITED_API |
Antoine Pitrou | f9d0b12 | 2012-12-09 14:28:26 +0100 | [diff] [blame] | 105 | /* This function returns the number of allocated memory blocks, regardless of size */ |
| 106 | PyAPI_FUNC(Py_ssize_t) _Py_GetAllocatedBlocks(void); |
Serhiy Storchaka | 9fab79b | 2016-09-11 11:03:14 +0300 | [diff] [blame] | 107 | #endif /* !Py_LIMITED_API */ |
Neil Schemenauer | 3e7b893 | 2002-04-12 02:38:45 +0000 | [diff] [blame] | 108 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 109 | /* Macros */ |
Neil Schemenauer | 3e7b893 | 2002-04-12 02:38:45 +0000 | [diff] [blame] | 110 | #ifdef WITH_PYMALLOC |
David Malcolm | 49526f4 | 2012-06-22 14:55:41 -0400 | [diff] [blame] | 111 | #ifndef Py_LIMITED_API |
Victor Stinner | 6bf992a | 2017-12-06 17:26:10 +0100 | [diff] [blame] | 112 | PyAPI_FUNC(int) _PyObject_DebugMallocStats(FILE *out); |
David Malcolm | 49526f4 | 2012-06-22 14:55:41 -0400 | [diff] [blame] | 113 | #endif /* #ifndef Py_LIMITED_API */ |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 114 | #endif |
Neil Schemenauer | 3e7b893 | 2002-04-12 02:38:45 +0000 | [diff] [blame] | 115 | |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 116 | /* Macros */ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 117 | #define PyObject_MALLOC PyObject_Malloc |
| 118 | #define PyObject_REALLOC PyObject_Realloc |
| 119 | #define PyObject_FREE PyObject_Free |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 120 | #define PyObject_Del PyObject_Free |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 121 | #define PyObject_DEL PyObject_Free |
| 122 | |
Neil Schemenauer | 3e7b893 | 2002-04-12 02:38:45 +0000 | [diff] [blame] | 123 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 124 | /* |
| 125 | * Generic object allocator interface |
| 126 | * ================================== |
| 127 | */ |
| 128 | |
| 129 | /* Functions */ |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 130 | PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *); |
| 131 | PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *, |
Martin v. Löwis | 18e1655 | 2006-02-15 17:27:45 +0000 | [diff] [blame] | 132 | PyTypeObject *, Py_ssize_t); |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 133 | PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *); |
Martin v. Löwis | 18e1655 | 2006-02-15 17:27:45 +0000 | [diff] [blame] | 134 | PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 135 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 136 | #define PyObject_New(type, typeobj) \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 137 | ( (type *) _PyObject_New(typeobj) ) |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 138 | #define PyObject_NewVar(type, typeobj, n) \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 139 | ( (type *) _PyObject_NewVar((typeobj), (n)) ) |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 140 | |
Victor Stinner | b4435e2 | 2018-10-26 14:35:00 +0200 | [diff] [blame] | 141 | /* Inline functions trading binary compatibility for speed: |
| 142 | PyObject_INIT() is the fast version of PyObject_Init(), and |
| 143 | PyObject_INIT_VAR() is the fast version of PyObject_InitVar. |
| 144 | See also pymem.h. |
| 145 | |
| 146 | These inline functions expect non-NULL object pointers. */ |
Victor Stinner | 542497a | 2018-10-29 14:49:24 +0100 | [diff] [blame] | 147 | static inline PyObject* |
Victor Stinner | b4435e2 | 2018-10-26 14:35:00 +0200 | [diff] [blame] | 148 | PyObject_INIT(PyObject *op, PyTypeObject *typeobj) |
| 149 | { |
| 150 | assert(op != NULL); |
| 151 | Py_TYPE(op) = typeobj; |
| 152 | _Py_NewReference(op); |
| 153 | return op; |
| 154 | } |
| 155 | |
Victor Stinner | 542497a | 2018-10-29 14:49:24 +0100 | [diff] [blame] | 156 | static inline PyVarObject* |
Victor Stinner | b4435e2 | 2018-10-26 14:35:00 +0200 | [diff] [blame] | 157 | PyObject_INIT_VAR(PyVarObject *op, PyTypeObject *typeobj, Py_ssize_t size) |
| 158 | { |
| 159 | assert(op != NULL); |
| 160 | Py_SIZE(op) = size; |
| 161 | PyObject_INIT((PyObject *)op, typeobj); |
| 162 | return op; |
| 163 | } |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 164 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 165 | #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize ) |
Tim Peters | 6d483d3 | 2001-10-06 21:27:34 +0000 | [diff] [blame] | 166 | |
Tim Peters | f2a67da | 2001-10-07 03:54:51 +0000 | [diff] [blame] | 167 | /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a |
| 168 | vrbl-size object with nitems items, exclusive of gc overhead (if any). The |
| 169 | value is rounded up to the closest multiple of sizeof(void *), in order to |
| 170 | ensure that pointer fields at the end of the object are correctly aligned |
| 171 | for the platform (this is of special importance for subclasses of, e.g., |
Serhiy Storchaka | 9594942 | 2013-08-27 19:40:23 +0300 | [diff] [blame] | 172 | str or int, so that pointers can be stored after the embedded data). |
Tim Peters | 6d483d3 | 2001-10-06 21:27:34 +0000 | [diff] [blame] | 173 | |
Tim Peters | f2a67da | 2001-10-07 03:54:51 +0000 | [diff] [blame] | 174 | Note that there's no memory wastage in doing this, as malloc has to |
| 175 | return (at worst) pointer-aligned memory anyway. |
Tim Peters | 6d483d3 | 2001-10-06 21:27:34 +0000 | [diff] [blame] | 176 | */ |
Tim Peters | f2a67da | 2001-10-07 03:54:51 +0000 | [diff] [blame] | 177 | #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0 |
| 178 | # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2" |
| 179 | #endif |
| 180 | |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 181 | #define _PyObject_VAR_SIZE(typeobj, nitems) \ |
Antoine Pitrou | ca8aa4a | 2012-09-20 20:56:47 +0200 | [diff] [blame] | 182 | _Py_SIZE_ROUND_UP((typeobj)->tp_basicsize + \ |
| 183 | (nitems)*(typeobj)->tp_itemsize, \ |
| 184 | SIZEOF_VOID_P) |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 185 | |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 186 | #define PyObject_NEW(type, typeobj) \ |
| 187 | ( (type *) PyObject_Init( \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 188 | (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) ) |
Tim Peters | 6d483d3 | 2001-10-06 21:27:34 +0000 | [diff] [blame] | 189 | |
Tim Peters | f2a67da | 2001-10-07 03:54:51 +0000 | [diff] [blame] | 190 | #define PyObject_NEW_VAR(type, typeobj, n) \ |
| 191 | ( (type *) PyObject_InitVar( \ |
| 192 | (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\ |
| 193 | (typeobj), (n)) ) |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 194 | |
| 195 | /* This example code implements an object constructor with a custom |
| 196 | allocator, where PyObject_New is inlined, and shows the important |
| 197 | distinction between two steps (at least): |
| 198 | 1) the actual allocation of the object storage; |
| 199 | 2) the initialization of the Python specific fields |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 200 | in this storage with PyObject_{Init, InitVar}. |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 201 | |
| 202 | PyObject * |
| 203 | YourObject_New(...) |
| 204 | { |
| 205 | PyObject *op; |
| 206 | |
| 207 | op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct)); |
| 208 | if (op == NULL) |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 209 | return PyErr_NoMemory(); |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 210 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 211 | PyObject_Init(op, &YourTypeStruct); |
Guido van Rossum | b18618d | 2000-05-03 23:44:39 +0000 | [diff] [blame] | 212 | |
| 213 | op->ob_field = value; |
| 214 | ... |
| 215 | return op; |
| 216 | } |
| 217 | |
| 218 | Note that in C++, the use of the new operator usually implies that |
| 219 | the 1st step is performed automatically for you, so in a C++ class |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 220 | constructor you would start directly with PyObject_Init/InitVar |
| 221 | */ |
Guido van Rossum | 5a84914 | 1996-07-21 02:23:54 +0000 | [diff] [blame] | 222 | |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 223 | #ifndef Py_LIMITED_API |
| 224 | typedef struct { |
| 225 | /* user context passed as the first argument to the 2 functions */ |
| 226 | void *ctx; |
| 227 | |
| 228 | /* allocate an arena of size bytes */ |
| 229 | void* (*alloc) (void *ctx, size_t size); |
| 230 | |
| 231 | /* free an arena */ |
| 232 | void (*free) (void *ctx, void *ptr, size_t size); |
| 233 | } PyObjectArenaAllocator; |
| 234 | |
| 235 | /* Get the arena allocator. */ |
| 236 | PyAPI_FUNC(void) PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator); |
| 237 | |
| 238 | /* Set the arena allocator. */ |
| 239 | PyAPI_FUNC(void) PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator); |
| 240 | #endif |
| 241 | |
| 242 | |
Jeremy Hylton | c5007aa | 2000-06-30 05:02:53 +0000 | [diff] [blame] | 243 | /* |
| 244 | * Garbage Collection Support |
| 245 | * ========================== |
| 246 | */ |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 247 | |
Łukasz Langa | fef7e94 | 2016-09-09 21:47:46 -0700 | [diff] [blame] | 248 | /* C equivalent of gc.collect() which ignores the state of gc.enabled. */ |
Neal Norwitz | 7b216c5 | 2006-03-04 20:01:53 +0000 | [diff] [blame] | 249 | PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void); |
Guido van Rossum | e13ddc9 | 2003-04-17 17:29:22 +0000 | [diff] [blame] | 250 | |
Antoine Pitrou | fef34e3 | 2013-05-19 01:11:58 +0200 | [diff] [blame] | 251 | #ifndef Py_LIMITED_API |
| 252 | PyAPI_FUNC(Py_ssize_t) _PyGC_CollectNoFail(void); |
Łukasz Langa | fef7e94 | 2016-09-09 21:47:46 -0700 | [diff] [blame] | 253 | PyAPI_FUNC(Py_ssize_t) _PyGC_CollectIfEnabled(void); |
Antoine Pitrou | fef34e3 | 2013-05-19 01:11:58 +0200 | [diff] [blame] | 254 | #endif |
| 255 | |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 256 | /* Test if a type has a GC head */ |
| 257 | #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 258 | |
Martin v. Löwis | 4129068 | 2006-02-16 14:56:14 +0000 | [diff] [blame] | 259 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t); |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 260 | #define PyObject_GC_Resize(type, op, n) \ |
Victor Stinner | 2ff8fb7 | 2018-11-22 02:57:29 +0100 | [diff] [blame^] | 261 | ( (type *) _PyObject_GC_Resize(_PyVarObject_CAST(op), (n)) ) |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 262 | |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 263 | |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 264 | #ifndef Py_LIMITED_API |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 265 | /* Test if an object has a GC head */ |
| 266 | #define PyObject_IS_GC(o) \ |
| 267 | (PyType_IS_GC(Py_TYPE(o)) \ |
| 268 | && (Py_TYPE(o)->tp_is_gc == NULL || Py_TYPE(o)->tp_is_gc(o))) |
| 269 | |
| 270 | /* GC information is stored BEFORE the object structure. */ |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 271 | typedef struct { |
| 272 | // Pointer to next object in the list. |
| 273 | // 0 means the object is not tracked |
| 274 | uintptr_t _gc_next; |
| 275 | |
| 276 | // Pointer to previous object in the list. |
| 277 | // Lowest two bits are used for flags documented later. |
| 278 | uintptr_t _gc_prev; |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 279 | } PyGC_Head; |
| 280 | |
Neil Schemenauer | ef99723 | 2002-03-28 21:06:16 +0000 | [diff] [blame] | 281 | #define _Py_AS_GC(o) ((PyGC_Head *)(o)-1) |
| 282 | |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 283 | /* True if the object is currently tracked by the GC. */ |
| 284 | #define _PyObject_GC_IS_TRACKED(o) (_Py_AS_GC(o)->_gc_next != 0) |
| 285 | |
| 286 | /* True if the object may be tracked by the GC in the future, or already is. |
| 287 | This can be useful to implement some optimizations. */ |
| 288 | #define _PyObject_GC_MAY_BE_TRACKED(obj) \ |
| 289 | (PyObject_IS_GC(obj) && \ |
| 290 | (!PyTuple_CheckExact(obj) || _PyObject_GC_IS_TRACKED(obj))) |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 291 | |
| 292 | |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 293 | /* Bit flags for _gc_prev */ |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 294 | /* Bit 0 is set when tp_finalize is called */ |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 295 | #define _PyGC_PREV_MASK_FINALIZED (1) |
| 296 | /* Bit 1 is set when the object is in generation which is GCed currently. */ |
| 297 | #define _PyGC_PREV_MASK_COLLECTING (2) |
| 298 | /* The (N-2) most significant bits contain the real address. */ |
| 299 | #define _PyGC_PREV_SHIFT (2) |
| 300 | #define _PyGC_PREV_MASK (((uintptr_t) -1) << _PyGC_PREV_SHIFT) |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 301 | |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 302 | // Lowest bit of _gc_next is used for flags only in GC. |
| 303 | // But it is always 0 for normal code. |
| 304 | #define _PyGCHead_NEXT(g) ((PyGC_Head*)(g)->_gc_next) |
| 305 | #define _PyGCHead_SET_NEXT(g, p) ((g)->_gc_next = (uintptr_t)(p)) |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 306 | |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 307 | // Lowest two bits of _gc_prev is used for _PyGC_PREV_MASK_* flags. |
| 308 | #define _PyGCHead_PREV(g) ((PyGC_Head*)((g)->_gc_prev & _PyGC_PREV_MASK)) |
| 309 | #define _PyGCHead_SET_PREV(g, p) do { \ |
| 310 | assert(((uintptr_t)p & ~_PyGC_PREV_MASK) == 0); \ |
| 311 | (g)->_gc_prev = ((g)->_gc_prev & ~_PyGC_PREV_MASK) \ |
| 312 | | ((uintptr_t)(p)); \ |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 313 | } while (0) |
| 314 | |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 315 | #define _PyGCHead_FINALIZED(g) \ |
| 316 | (((g)->_gc_prev & _PyGC_PREV_MASK_FINALIZED) != 0) |
| 317 | #define _PyGCHead_SET_FINALIZED(g) \ |
| 318 | ((g)->_gc_prev |= _PyGC_PREV_MASK_FINALIZED) |
INADA Naoki | 5ac9e6e | 2018-07-10 17:19:53 +0900 | [diff] [blame] | 319 | |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 320 | #define _PyGC_FINALIZED(o) \ |
| 321 | _PyGCHead_FINALIZED(_Py_AS_GC(o)) |
| 322 | #define _PyGC_SET_FINALIZED(o) \ |
| 323 | _PyGCHead_SET_FINALIZED(_Py_AS_GC(o)) |
Victor Stinner | 3e21ad1 | 2018-11-21 00:43:09 +0100 | [diff] [blame] | 324 | #endif /* !defined(Py_LIMITED_API) */ |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 325 | |
Serhiy Storchaka | 9fab79b | 2016-09-11 11:03:14 +0300 | [diff] [blame] | 326 | #ifndef Py_LIMITED_API |
Victor Stinner | db067af | 2014-05-02 22:31:14 +0200 | [diff] [blame] | 327 | PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t size); |
| 328 | PyAPI_FUNC(PyObject *) _PyObject_GC_Calloc(size_t size); |
Serhiy Storchaka | 9fab79b | 2016-09-11 11:03:14 +0300 | [diff] [blame] | 329 | #endif /* !Py_LIMITED_API */ |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 330 | PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *); |
Martin v. Löwis | 18e1655 | 2006-02-15 17:27:45 +0000 | [diff] [blame] | 331 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t); |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 332 | |
| 333 | /* Tell the GC to track this object. |
| 334 | * |
| 335 | * See also private _PyObject_GC_TRACK() macro. */ |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 336 | PyAPI_FUNC(void) PyObject_GC_Track(void *); |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 337 | |
| 338 | /* Tell the GC to stop tracking this object. |
| 339 | * |
| 340 | * See also private _PyObject_GC_UNTRACK() macro. */ |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 341 | PyAPI_FUNC(void) PyObject_GC_UnTrack(void *); |
Victor Stinner | 1a6be91 | 2018-11-13 12:52:18 +0100 | [diff] [blame] | 342 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 343 | PyAPI_FUNC(void) PyObject_GC_Del(void *); |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 344 | |
| 345 | #define PyObject_GC_New(type, typeobj) \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 346 | ( (type *) _PyObject_GC_New(typeobj) ) |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 347 | #define PyObject_GC_NewVar(type, typeobj, n) \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 348 | ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) |
Neil Schemenauer | 3e7b893 | 2002-04-12 02:38:45 +0000 | [diff] [blame] | 349 | |
Neil Schemenauer | 74b5ade | 2001-08-29 23:49:28 +0000 | [diff] [blame] | 350 | |
Tim Peters | eda2930 | 2004-07-15 04:05:59 +0000 | [diff] [blame] | 351 | /* Utility macro to help write tp_traverse functions. |
| 352 | * To use this macro, the tp_traverse function must name its arguments |
| 353 | * "visit" and "arg". This is intended to keep tp_traverse functions |
| 354 | * looking as much alike as possible. |
| 355 | */ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 356 | #define Py_VISIT(op) \ |
| 357 | do { \ |
| 358 | if (op) { \ |
Victor Stinner | 2ff8fb7 | 2018-11-22 02:57:29 +0100 | [diff] [blame^] | 359 | int vret = visit(_PyObject_CAST(op), arg); \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 360 | if (vret) \ |
| 361 | return vret; \ |
| 362 | } \ |
| 363 | } while (0) |
Jim Fulton | aa6389e | 2004-07-14 19:08:17 +0000 | [diff] [blame] | 364 | |
Jeremy Hylton | d08b4c4 | 2000-06-23 19:37:02 +0000 | [diff] [blame] | 365 | |
Fred Drake | 41deb1e | 2001-02-01 05:27:45 +0000 | [diff] [blame] | 366 | /* Test if a type supports weak references */ |
Christian Tismer | ea62ce7 | 2018-06-09 20:32:25 +0200 | [diff] [blame] | 367 | #ifndef Py_LIMITED_API |
Guido van Rossum | 3cf5b1e | 2006-07-27 21:53:35 +0000 | [diff] [blame] | 368 | #define PyType_SUPPORTS_WEAKREFS(t) ((t)->tp_weaklistoffset > 0) |
Fred Drake | 41deb1e | 2001-02-01 05:27:45 +0000 | [diff] [blame] | 369 | |
| 370 | #define PyObject_GET_WEAKREFS_LISTPTR(o) \ |
Antoine Pitrou | f95a1b3 | 2010-05-09 15:52:27 +0000 | [diff] [blame] | 371 | ((PyObject **) (((char *) (o)) + Py_TYPE(o)->tp_weaklistoffset)) |
Christian Tismer | ea62ce7 | 2018-06-09 20:32:25 +0200 | [diff] [blame] | 372 | #endif |
Fred Drake | 41deb1e | 2001-02-01 05:27:45 +0000 | [diff] [blame] | 373 | |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 374 | #ifdef __cplusplus |
| 375 | } |
| 376 | #endif |
| 377 | #endif /* !Py_OBJIMPL_H */ |