Debian Codegraph @

Include/internal/pycore_gc.h

raw
1 #ifndef Py_INTERNAL_GC_H
2 #define Py_INTERNAL_GC_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif
6
7 #ifndef Py_BUILD_CORE
8 # error "this header requires Py_BUILD_CORE define"
9 #endif
10
11 #include "pycore_interp_structs.h" // PyGC_Head
12 #include "pycore_pystate.h" // _PyInterpreterState_GET()
13 #include "pycore_typedefs.h" // _PyInterpreterFrame
14
15
16 /* Get an object's GC head */
17 static inline PyGC_Head* _Py_AS_GC(PyObject *op) {
18 char *gc = ((char*)op) - sizeof(PyGC_Head);
19 return (PyGC_Head*)gc;
20 }
21
22 /* Get the object given the GC head */
23 static inline PyObject* _Py_FROM_GC(PyGC_Head *gc) {
24 char *op = ((char *)gc) + sizeof(PyGC_Head);
25 return (PyObject *)op;
26 }
27
28
29 /* Bit flags for ob_gc_bits (in Py_GIL_DISABLED builds)
30 *
31 * Setting the bits requires a relaxed store. The per-object lock must also be
32 * held, except when the object is only visible to a single thread (e.g. during
33 * object initialization or destruction).
34 *
35 * Reading the bits requires using a relaxed load, but does not require holding
36 * the per-object lock.
37 */
38 #ifdef Py_GIL_DISABLED
39 # define _PyGC_BITS_TRACKED (1<<0) // Tracked by the GC
40 # define _PyGC_BITS_FINALIZED (1<<1) // tp_finalize was called
41 # define _PyGC_BITS_UNREACHABLE (1<<2)
42 # define _PyGC_BITS_FROZEN (1<<3)
43 # define _PyGC_BITS_SHARED (1<<4)
44 # define _PyGC_BITS_ALIVE (1<<5) // Reachable from a known root.
45 # define _PyGC_BITS_DEFERRED (1<<6) // Use deferred reference counting
46 #endif
47
48 #ifdef Py_GIL_DISABLED
49
50 static inline void
51 _PyObject_SET_GC_BITS(PyObject *op, uint8_t new_bits)
52 {
53 uint8_t bits = _Py_atomic_load_uint8_relaxed(&op->ob_gc_bits);
54 _Py_atomic_store_uint8_relaxed(&op->ob_gc_bits, bits | new_bits);
55 }
56
57 static inline int
58 _PyObject_HAS_GC_BITS(PyObject *op, uint8_t bits)
59 {
60 return (_Py_atomic_load_uint8_relaxed(&op->ob_gc_bits) & bits) != 0;
61 }
62
63 static inline void
64 _PyObject_CLEAR_GC_BITS(PyObject *op, uint8_t bits_to_clear)
65 {
66 uint8_t bits = _Py_atomic_load_uint8_relaxed(&op->ob_gc_bits);
67 _Py_atomic_store_uint8_relaxed(&op->ob_gc_bits, bits & ~bits_to_clear);
68 }
69
70 #endif
71
72 /* True if the object is currently tracked by the GC. */
73 static inline int _PyObject_GC_IS_TRACKED(PyObject *op) {
74 #ifdef Py_GIL_DISABLED
75 return _PyObject_HAS_GC_BITS(op, _PyGC_BITS_TRACKED);
76 #else
77 PyGC_Head *gc = _Py_AS_GC(op);
78 return (gc->_gc_next != 0);
79 #endif
80 }
81 #define _PyObject_GC_IS_TRACKED(op) _PyObject_GC_IS_TRACKED(_Py_CAST(PyObject*, op))
82
83 /* True if the object may be tracked by the GC in the future, or already is.
84 This can be useful to implement some optimizations. */
85 static inline int _PyObject_GC_MAY_BE_TRACKED(PyObject *obj) {
86 if (!PyObject_IS_GC(obj)) {
87 return 0;
88 }
89 if (PyTuple_CheckExact(obj)) {
90 return _PyObject_GC_IS_TRACKED(obj);
91 }
92 return 1;
93 }
94
95 #ifdef Py_GIL_DISABLED
96
97 /* True if memory the object references is shared between
98 * multiple threads and needs special purpose when freeing
99 * those references due to the possibility of in-flight
100 * lock-free reads occurring. The object is responsible
101 * for calling _PyMem_FreeDelayed on the referenced
102 * memory. */
103 static inline int _PyObject_GC_IS_SHARED(PyObject *op) {
104 return _PyObject_HAS_GC_BITS(op, _PyGC_BITS_SHARED);
105 }
106 #define _PyObject_GC_IS_SHARED(op) _PyObject_GC_IS_SHARED(_Py_CAST(PyObject*, op))
107
108 static inline void _PyObject_GC_SET_SHARED(PyObject *op) {
109 _PyObject_SET_GC_BITS(op, _PyGC_BITS_SHARED);
110 }
111 #define _PyObject_GC_SET_SHARED(op) _PyObject_GC_SET_SHARED(_Py_CAST(PyObject*, op))
112
113 #endif
114
115 /* Bit flags for _gc_prev */
116 /* Bit 0 is set when tp_finalize is called */
117 #define _PyGC_PREV_MASK_FINALIZED ((uintptr_t)1)
118 /* Bit 1 is set when the object is in generation which is GCed currently. */
119 #define _PyGC_PREV_MASK_COLLECTING ((uintptr_t)2)
120
121 #define _PyGC_PREV_SHIFT 2
122 #define _PyGC_PREV_MASK (((uintptr_t) -1) << _PyGC_PREV_SHIFT)
123
124 /* set for debugging information */
125 #define _PyGC_DEBUG_STATS (1<<0) /* print collection statistics */
126 #define _PyGC_DEBUG_COLLECTABLE (1<<1) /* print collectable objects */
127 #define _PyGC_DEBUG_UNCOLLECTABLE (1<<2) /* print uncollectable objects */
128 #define _PyGC_DEBUG_SAVEALL (1<<5) /* save all garbage in gc.garbage */
129 #define _PyGC_DEBUG_LEAK _PyGC_DEBUG_COLLECTABLE | \
130 _PyGC_DEBUG_UNCOLLECTABLE | \
131 _PyGC_DEBUG_SAVEALL
132
133 typedef enum {
134 // GC was triggered by heap allocation
135 _Py_GC_REASON_HEAP,
136
137 // GC was called during shutdown
138 _Py_GC_REASON_SHUTDOWN,
139
140 // GC was called by gc.collect() or PyGC_Collect()
141 _Py_GC_REASON_MANUAL
142 } _PyGC_Reason;
143
144 // Lowest bit of _gc_next is used for flags only in GC.
145 // But it is always 0 for normal code.
146 static inline PyGC_Head* _PyGCHead_NEXT(PyGC_Head *gc) {
147 uintptr_t next = gc->_gc_next;
148 return (PyGC_Head*)next;
149 }
150 static inline void _PyGCHead_SET_NEXT(PyGC_Head *gc, PyGC_Head *next) {
151 gc->_gc_next = (uintptr_t)next;
152 }
153
154 // Lowest two bits of _gc_prev is used for _PyGC_PREV_MASK_* flags.
155 static inline PyGC_Head* _PyGCHead_PREV(PyGC_Head *gc) {
156 uintptr_t prev = (gc->_gc_prev & _PyGC_PREV_MASK);
157 return (PyGC_Head*)prev;
158 }
159
160 static inline void _PyGCHead_SET_PREV(PyGC_Head *gc, PyGC_Head *prev) {
161 uintptr_t uprev = (uintptr_t)prev;
162 assert((uprev & ~_PyGC_PREV_MASK) == 0);
163 gc->_gc_prev = ((gc->_gc_prev & ~_PyGC_PREV_MASK) | uprev);
164 }
165
166 static inline int _PyGC_FINALIZED(PyObject *op) {
167 #ifdef Py_GIL_DISABLED
168 return _PyObject_HAS_GC_BITS(op, _PyGC_BITS_FINALIZED);
169 #else
170 PyGC_Head *gc = _Py_AS_GC(op);
171 return ((gc->_gc_prev & _PyGC_PREV_MASK_FINALIZED) != 0);
172 #endif
173 }
174 static inline void _PyGC_SET_FINALIZED(PyObject *op) {
175 #ifdef Py_GIL_DISABLED
176 _PyObject_SET_GC_BITS(op, _PyGC_BITS_FINALIZED);
177 #else
178 PyGC_Head *gc = _Py_AS_GC(op);
179 gc->_gc_prev |= _PyGC_PREV_MASK_FINALIZED;
180 #endif
181 }
182 static inline void _PyGC_CLEAR_FINALIZED(PyObject *op) {
183 #ifdef Py_GIL_DISABLED
184 _PyObject_CLEAR_GC_BITS(op, _PyGC_BITS_FINALIZED);
185 #else
186 PyGC_Head *gc = _Py_AS_GC(op);
187 gc->_gc_prev &= ~_PyGC_PREV_MASK_FINALIZED;
188 #endif
189 }
190
191 extern void _Py_ScheduleGC(PyThreadState *tstate);
192
193
194 /* Tell the GC to track this object.
195 *
196 * The object must not be tracked by the GC.
197 *
198 * NB: While the object is tracked by the collector, it must be safe to call the
199 * ob_traverse method.
200 *
201 * Internal note: interp->gc.generation0->_gc_prev doesn't have any bit flags
202 * because it's not an object header. So we don't use _PyGCHead_PREV() and
203 * _PyGCHead_SET_PREV() for it to avoid unnecessary bitwise operations.
204 *
205 * See also the public PyObject_GC_Track() function.
206 */
207 static inline void _PyObject_GC_TRACK(
208 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined
209 #ifndef NDEBUG
210 const char *filename, int lineno,
211 #endif
212 PyObject *op)
213 {
214 _PyObject_ASSERT_FROM(op, !_PyObject_GC_IS_TRACKED(op),
215 "object already tracked by the garbage collector",
216 filename, lineno, __func__);
217 #ifdef Py_GIL_DISABLED
218 _PyObject_SET_GC_BITS(op, _PyGC_BITS_TRACKED);
219 #else
220 PyGC_Head *gc = _Py_AS_GC(op);
221 _PyObject_ASSERT_FROM(op,
222 (gc->_gc_prev & _PyGC_PREV_MASK_COLLECTING) == 0,
223 "object is in generation which is garbage collected",
224 filename, lineno, __func__);
225
226 struct _gc_runtime_state *gcstate = &_PyInterpreterState_GET()->gc;
227 PyGC_Head *generation0 = gcstate->generation0;
228 PyGC_Head *last = (PyGC_Head*)(generation0->_gc_prev);
229 _PyGCHead_SET_NEXT(last, gc);
230 _PyGCHead_SET_PREV(gc, last);
231 _PyGCHead_SET_NEXT(gc, generation0);
232 generation0->_gc_prev = (uintptr_t)gc;
233 gcstate->heap_size++;
234 #endif
235 }
236
237 /* Tell the GC to stop tracking this object.
238 *
239 * Internal note: This may be called while GC. So _PyGC_PREV_MASK_COLLECTING
240 * must be cleared. But _PyGC_PREV_MASK_FINALIZED bit is kept.
241 *
242 * The object must be tracked by the GC.
243 *
244 * See also the public PyObject_GC_UnTrack() which accept an object which is
245 * not tracked.
246 */
247 static inline void _PyObject_GC_UNTRACK(
248 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined
249 #ifndef NDEBUG
250 const char *filename, int lineno,
251 #endif
252 PyObject *op)
253 {
254 _PyObject_ASSERT_FROM(op, _PyObject_GC_IS_TRACKED(op),
255 "object not tracked by the garbage collector",
256 filename, lineno, __func__);
257
258 #ifdef Py_GIL_DISABLED
259 _PyObject_CLEAR_GC_BITS(op, _PyGC_BITS_TRACKED);
260 #else
261 PyGC_Head *gc = _Py_AS_GC(op);
262 PyGC_Head *prev = _PyGCHead_PREV(gc);
263 PyGC_Head *next = _PyGCHead_NEXT(gc);
264 _PyGCHead_SET_NEXT(prev, next);
265 _PyGCHead_SET_PREV(next, prev);
266 gc->_gc_next = 0;
267 gc->_gc_prev &= _PyGC_PREV_MASK_FINALIZED;
268 struct _gc_runtime_state *gcstate = &_PyInterpreterState_GET()->gc;
269 gcstate->heap_size--;
270 #endif
271 }
272
273
274
275 /*
276 NOTE: about untracking of mutable objects.
277
278 Certain types of container cannot participate in a reference cycle, and
279 so do not need to be tracked by the garbage collector. Untracking these
280 objects reduces the cost of garbage collections. However, determining
281 which objects may be untracked is not free, and the costs must be
282 weighed against the benefits for garbage collection.
283
284 There are two possible strategies for when to untrack a container:
285
286 i) When the container is created.
287 ii) When the container is examined by the garbage collector.
288
289 Tuples containing only immutable objects (integers, strings etc, and
290 recursively, tuples of immutable objects) do not need to be tracked.
291 The interpreter creates a large number of tuples, many of which will
292 not survive until garbage collection. It is therefore not worthwhile
293 to untrack eligible tuples at creation time.
294
295 Instead, all tuples except the empty tuple are tracked when created.
296 During garbage collection it is determined whether any surviving tuples
297 can be untracked. A tuple can be untracked if all of its contents are
298 already not tracked. Tuples are examined for untracking in all garbage
299 collection cycles. It may take more than one cycle to untrack a tuple.
300
301 Dictionaries containing only immutable objects also do not need to be
302 tracked. Dictionaries are untracked when created. If a tracked item is
303 inserted into a dictionary (either as a key or value), the dictionary
304 becomes tracked. During a full garbage collection (all generations),
305 the collector will untrack any dictionaries whose contents are not
306 tracked.
307
308 The module provides the python function is_tracked(obj), which returns
309 the CURRENT tracking status of the object. Subsequent garbage
310 collections may change the tracking status of the object.
311
312 Untracking of certain containers was introduced in issue #4688, and
313 the algorithm was refined in response to issue #14775.
314 */
315
316 extern void _PyGC_InitState(struct _gc_runtime_state *);
317
318 extern Py_ssize_t _PyGC_Collect(PyThreadState *tstate, int generation, _PyGC_Reason reason);
319 extern void _PyGC_CollectNoFail(PyThreadState *tstate);
320
321 /* Freeze objects tracked by the GC and ignore them in future collections. */
322 extern void _PyGC_Freeze(PyInterpreterState *interp);
323 /* Unfreezes objects placing them in the oldest generation */
324 extern void _PyGC_Unfreeze(PyInterpreterState *interp);
325 /* Number of frozen objects */
326 extern Py_ssize_t _PyGC_GetFreezeCount(PyInterpreterState *interp);
327
328 extern PyObject *_PyGC_GetObjects(PyInterpreterState *interp, int generation);
329 extern PyObject *_PyGC_GetReferrers(PyInterpreterState *interp, PyObject *objs);
330
331 // Functions to clear types free lists
332 extern void _PyGC_ClearAllFreeLists(PyInterpreterState *interp);
333 extern void _Py_RunGC(PyThreadState *tstate);
334
335 union _PyStackRef;
336
337 // GC visit callback for tracked interpreter frames
338 extern int _PyGC_VisitFrameStack(_PyInterpreterFrame *frame, visitproc visit, void *arg);
339 extern int _PyGC_VisitStackRef(union _PyStackRef *ref, visitproc visit, void *arg);
340
341 #ifdef Py_GIL_DISABLED
342 extern void _PyGC_VisitObjectsWorldStopped(PyInterpreterState *interp,
343 gcvisitobjects_t callback, void *arg);
344 #endif
345
346 #ifdef __cplusplus
347 }
348 #endif
349 #endif /* !Py_INTERNAL_GC_H */