python3.12/internal/pycore_gc.h

0001 #ifndef Py_INTERNAL_GC_H
0002 #define Py_INTERNAL_GC_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 #ifndef Py_BUILD_CORE
0008 #  error "this header requires Py_BUILD_CORE define"
0009 #endif
0010
0011 /* GC information is stored BEFORE the object structure. */
0012 typedef struct {
0013     // Pointer to next object in the list.
0014     // 0 means the object is not tracked
0015     uintptr_t _gc_next;
0016
0017     // Pointer to previous object in the list.
0018     // Lowest two bits are used for flags documented later.
0019     uintptr_t _gc_prev;
0020 } PyGC_Head;
0021
0022 static inline PyGC_Head* _Py_AS_GC(PyObject *op) {
0023     return (_Py_CAST(PyGC_Head*, op) - 1);
0024 }
0025 #define _PyGC_Head_UNUSED PyGC_Head
0026
0027 /* True if the object is currently tracked by the GC. */
0028 static inline int _PyObject_GC_IS_TRACKED(PyObject *op) {
0029     PyGC_Head *gc = _Py_AS_GC(op);
0030     return (gc->_gc_next != 0);
0031 }
0032 #define _PyObject_GC_IS_TRACKED(op) _PyObject_GC_IS_TRACKED(_Py_CAST(PyObject*, op))
0033
0034 /* True if the object may be tracked by the GC in the future, or already is.
0035    This can be useful to implement some optimizations. */
0036 static inline int _PyObject_GC_MAY_BE_TRACKED(PyObject *obj) {
0037     if (!PyObject_IS_GC(obj)) {
0038         return 0;
0039     }
0040     if (PyTuple_CheckExact(obj)) {
0041         return _PyObject_GC_IS_TRACKED(obj);
0042     }
0043     return 1;
0044 }
0045
0046
0047 /* Bit flags for _gc_prev */
0048 /* Bit 0 is set when tp_finalize is called */
0049 #define _PyGC_PREV_MASK_FINALIZED  (1)
0050 /* Bit 1 is set when the object is in generation which is GCed currently. */
0051 #define _PyGC_PREV_MASK_COLLECTING (2)
0052 /* The (N-2) most significant bits contain the real address. */
0053 #define _PyGC_PREV_SHIFT           (2)
0054 #define _PyGC_PREV_MASK            (((uintptr_t) -1) << _PyGC_PREV_SHIFT)
0055
0056 // Lowest bit of _gc_next is used for flags only in GC.
0057 // But it is always 0 for normal code.
0058 static inline PyGC_Head* _PyGCHead_NEXT(PyGC_Head *gc) {
0059     uintptr_t next = gc->_gc_next;
0060     return _Py_CAST(PyGC_Head*, next);
0061 }
0062 static inline void _PyGCHead_SET_NEXT(PyGC_Head *gc, PyGC_Head *next) {
0063     gc->_gc_next = _Py_CAST(uintptr_t, next);
0064 }
0065
0066 // Lowest two bits of _gc_prev is used for _PyGC_PREV_MASK_* flags.
0067 static inline PyGC_Head* _PyGCHead_PREV(PyGC_Head *gc) {
0068     uintptr_t prev = (gc->_gc_prev & _PyGC_PREV_MASK);
0069     return _Py_CAST(PyGC_Head*, prev);
0070 }
0071 static inline void _PyGCHead_SET_PREV(PyGC_Head *gc, PyGC_Head *prev) {
0072     uintptr_t uprev = _Py_CAST(uintptr_t, prev);
0073     assert((uprev & ~_PyGC_PREV_MASK) == 0);
0074     gc->_gc_prev = ((gc->_gc_prev & ~_PyGC_PREV_MASK) | uprev);
0075 }
0076
0077 static inline int _PyGCHead_FINALIZED(PyGC_Head *gc) {
0078     return ((gc->_gc_prev & _PyGC_PREV_MASK_FINALIZED) != 0);
0079 }
0080 static inline void _PyGCHead_SET_FINALIZED(PyGC_Head *gc) {
0081     gc->_gc_prev |= _PyGC_PREV_MASK_FINALIZED;
0082 }
0083
0084 static inline int _PyGC_FINALIZED(PyObject *op) {
0085     PyGC_Head *gc = _Py_AS_GC(op);
0086     return _PyGCHead_FINALIZED(gc);
0087 }
0088 static inline void _PyGC_SET_FINALIZED(PyObject *op) {
0089     PyGC_Head *gc = _Py_AS_GC(op);
0090     _PyGCHead_SET_FINALIZED(gc);
0091 }
0092
0093
0094 /* GC runtime state */
0095
0096 /* If we change this, we need to change the default value in the
0097    signature of gc.collect. */
0098 #define NUM_GENERATIONS 3
0099 /*
0100    NOTE: about untracking of mutable objects.
0101
0102    Certain types of container cannot participate in a reference cycle, and
0103    so do not need to be tracked by the garbage collector. Untracking these
0104    objects reduces the cost of garbage collections. However, determining
0105    which objects may be untracked is not free, and the costs must be
0106    weighed against the benefits for garbage collection.
0107
0108    There are two possible strategies for when to untrack a container:
0109
0110    i) When the container is created.
0111    ii) When the container is examined by the garbage collector.
0112
0113    Tuples containing only immutable objects (integers, strings etc, and
0114    recursively, tuples of immutable objects) do not need to be tracked.
0115    The interpreter creates a large number of tuples, many of which will
0116    not survive until garbage collection. It is therefore not worthwhile
0117    to untrack eligible tuples at creation time.
0118
0119    Instead, all tuples except the empty tuple are tracked when created.
0120    During garbage collection it is determined whether any surviving tuples
0121    can be untracked. A tuple can be untracked if all of its contents are
0122    already not tracked. Tuples are examined for untracking in all garbage
0123    collection cycles. It may take more than one cycle to untrack a tuple.
0124
0125    Dictionaries containing only immutable objects also do not need to be
0126    tracked. Dictionaries are untracked when created. If a tracked item is
0127    inserted into a dictionary (either as a key or value), the dictionary
0128    becomes tracked. During a full garbage collection (all generations),
0129    the collector will untrack any dictionaries whose contents are not
0130    tracked.
0131
0132    The module provides the python function is_tracked(obj), which returns
0133    the CURRENT tracking status of the object. Subsequent garbage
0134    collections may change the tracking status of the object.
0135
0136    Untracking of certain containers was introduced in issue #4688, and
0137    the algorithm was refined in response to issue #14775.
0138 */
0139
0140 struct gc_generation {
0141     PyGC_Head head;
0142     int threshold; /* collection threshold */
0143     int count; /* count of allocations or collections of younger
0144                   generations */
0145 };
0146
0147 /* Running stats per generation */
0148 struct gc_generation_stats {
0149     /* total number of collections */
0150     Py_ssize_t collections;
0151     /* total number of collected objects */
0152     Py_ssize_t collected;
0153     /* total number of uncollectable objects (put into gc.garbage) */
0154     Py_ssize_t uncollectable;
0155 };
0156
0157 struct _gc_runtime_state {
0158     /* List of objects that still need to be cleaned up, singly linked
0159      * via their gc headers' gc_prev pointers.  */
0160     PyObject *trash_delete_later;
0161     /* Current call-stack depth of tp_dealloc calls. */
0162     int trash_delete_nesting;
0163
0164     /* Is automatic collection enabled? */
0165     int enabled;
0166     int debug;
0167     /* linked lists of container objects */
0168     struct gc_generation generations[NUM_GENERATIONS];
0169     PyGC_Head *generation0;
0170     /* a permanent generation which won't be collected */
0171     struct gc_generation permanent_generation;
0172     struct gc_generation_stats generation_stats[NUM_GENERATIONS];
0173     /* true if we are currently running the collector */
0174     int collecting;
0175     /* list of uncollectable objects */
0176     PyObject *garbage;
0177     /* a list of callbacks to be invoked when collection is performed */
0178     PyObject *callbacks;
0179     /* This is the number of objects that survived the last full
0180        collection. It approximates the number of long lived objects
0181        tracked by the GC.
0182
0183        (by "full collection", we mean a collection of the oldest
0184        generation). */
0185     Py_ssize_t long_lived_total;
0186     /* This is the number of objects that survived all "non-full"
0187        collections, and are awaiting to undergo a full collection for
0188        the first time. */
0189     Py_ssize_t long_lived_pending;
0190 };
0191
0192
0193 extern void _PyGC_InitState(struct _gc_runtime_state *);
0194
0195 extern Py_ssize_t _PyGC_CollectNoFail(PyThreadState *tstate);
0196
0197
0198 // Functions to clear types free lists
0199 extern void _PyTuple_ClearFreeList(PyInterpreterState *interp);
0200 extern void _PyFloat_ClearFreeList(PyInterpreterState *interp);
0201 extern void _PyList_ClearFreeList(PyInterpreterState *interp);
0202 extern void _PyDict_ClearFreeList(PyInterpreterState *interp);
0203 extern void _PyAsyncGen_ClearFreeLists(PyInterpreterState *interp);
0204 extern void _PyContext_ClearFreeList(PyInterpreterState *interp);
0205 extern void _Py_ScheduleGC(PyInterpreterState *interp);
0206 extern void _Py_RunGC(PyThreadState *tstate);
0207
0208 #ifdef __cplusplus
0209 }
0210 #endif
0211 #endif /* !Py_INTERNAL_GC_H */