This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation:
Functions¶gc.enable()¶Enable automatic garbage collection. gc.disable()¶Disable automatic garbage collection. Heap memory can still be allocated, and garbage collection can still be initiated manually using
Run a garbage collection. gc.mem_alloc()¶Return the number of bytes of heap RAM that are allocated. Difference to CPython This function is MicroPython extension. gc.mem_free()¶Return the number of bytes of available heap RAM, or -1 if this amount is not known. Difference to CPython This function is MicroPython extension. gc.threshold([amount])¶Set or query the additional GC allocation threshold. Normally, a collection is triggered only when a new allocation cannot be satisfied, i.e. on an out-of-memory (OOM) condition. If this function is called, in addition to OOM, a collection will be triggered each time after amount bytes have been allocated (in total, since the previous time such an amount of bytes have been allocated). amount is usually specified as less than the full heap size, with the intention to trigger a collection earlier than when the heap becomes exhausted, and in the hope that an early collection will prevent excessive memory fragmentation. This is a heuristic measure, the effect of which will vary from application to application, as well as the optimal value of the amount parameter. Calling the function without argument will return the current value of the threshold. A value of -1 means a disabled allocation threshold. Difference to CPython This function is a MicroPython extension. CPython has a similar function - This module provides an interface to the optional garbage collector. It provides the ability to disable the collector, tune the collection frequency, and set debugging options. It also provides access to unreachable objects that the collector found but cannot free. Since the collector supplements the reference counting already used in Python, you can disable the collector if you are sure your program does not create reference cycles. Automatic collection can be
disabled by calling The gc. enable ()¶Enable automatic garbage collection. gc. disable ()¶Disable automatic garbage collection. gc. isenabled ()¶Return gc. collect (generation=2)¶With no arguments, run a full collection. The optional argument generation may be an integer specifying which generation to collect (from 0 to 2). A The free lists maintained for a number of built-in types are cleared whenever a full collection or
collection of the highest generation (2) is run. Not all items in some free lists may be freed due to the particular implementation, in particular gc. set_debug (flags)¶Set the garbage collection debugging flags. Debugging information will be written to gc. get_debug ()¶Return the debugging flags currently set. gc. get_objects (generation=None)¶Returns a list of all objects tracked by the collector, excluding the list returned. If generation is not None, return only the objects tracked by the collector that are in that generation. Changed in version 3.8: New generation parameter. Raises an auditing event gc. get_stats ()¶Return a list of three per-generation dictionaries containing collection statistics since interpreter start. The number of keys may change in the future, but currently each dictionary will contain the following items:
New in version 3.4. gc. set_threshold (threshold0[, threshold1[, threshold2]])¶Set the garbage collection thresholds (the collection frequency). Setting threshold0 to zero disables collection. The GC classifies objects into three generations depending on how many
collection sweeps they have survived. New objects are placed in the youngest generation (generation gc. get_count ()¶Return the current collection counts as a tuple of gc. get_threshold ()¶Return the current collection thresholds as a tuple of gc. get_referrers (*objs)¶Return the list of objects that directly refer to any of objs. This function will only locate those containers which support garbage collection; extension types which do refer to other objects but do not support garbage collection will not be found. Note that objects which have already
been dereferenced, but which live in cycles and have not yet been collected by the garbage collector can be listed among the resulting referrers. To get only currently live objects, call Warning Care must be taken when using objects returned by Raises an auditing event
gc. get_referents (*objs)¶Return a list of objects directly referred to by any of the arguments. The referents returned are those objects visited by the arguments’ C-level Raises an auditing event gc. is_tracked (obj)¶Returns >>> gc.is_tracked(0) False >>> gc.is_tracked("a") False >>> gc.is_tracked([]) True >>> gc.is_tracked({}) False >>> gc.is_tracked({"a": 1}) False >>> gc.is_tracked({"a": []}) True New in version 3.1. gc. is_finalized (obj)¶Returns >>> x = None >>> class Lazarus: ... def __del__(self): ... global x ... x = self ... >>> lazarus = Lazarus() >>> gc.is_finalized(lazarus) False >>> del lazarus >>> gc.is_finalized(x) True New in version 3.9. gc. freeze ()¶Freeze all the objects tracked by gc - move them to a permanent generation and ignore all the future collections. This can be used before a POSIX fork() call to make the gc copy-on-write friendly or to speed up collection. Also collection before a POSIX fork() call may free pages for future allocation which can cause copy-on-write too so it’s advised to disable gc in parent process and freeze before fork and enable gc in child process. New in version 3.7. gc. unfreeze ()¶Unfreeze the objects in the permanent generation, put them back into the oldest generation. New in version 3.7. gc. get_freeze_count ()¶Return the number of objects in the permanent generation. New in version 3.7. The following variables are provided for read-only access (you can mutate the values but should not rebind them): gc. garbage ¶A list of objects which the collector found to be unreachable but could not be freed (uncollectable objects). Starting with Python 3.4, this list should be empty most of the time, except when using instances of C extension types with a non- If Changed in version 3.4: Following PEP 442, objects with a
gc. callbacks ¶A list of callbacks that will be invoked by the garbage collector before and after collection. The callbacks will be called with two arguments, phase and info. phase can be one of two values:
info is a dict providing more information for the callback. The following keys are currently defined:
Applications can add their own callbacks to this list. The primary use cases are:
New in version 3.3. The following constants are provided for use with gc. DEBUG_STATS ¶Print statistics during collection. This information can be useful when tuning the collection frequency. gc. DEBUG_COLLECTABLE ¶Print information on collectable objects found. gc. DEBUG_UNCOLLECTABLE ¶Print information of uncollectable objects found (objects which are not reachable but cannot be freed by the collector). These objects will be added to the Changed in version 3.2: Also print the contents of the gc. DEBUG_SAVEALL ¶When set, all unreachable objects found will be appended to garbage rather than being freed. This can be useful for debugging a leaking program. gc. DEBUG_LEAK ¶The debugging flags necessary for the collector to print information about a leaking program (equal to |