gc – control the garbage collector
This module implements a subset of the corresponding CPython module,
as described below. For more information, refer to the original
CPython documentation: gc.
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
gc.collect().
- gc.isenabled()
Returns True if automatic garbage collection is enabled, and False otherwise.
- gc.collect()
Run a garbage collection.
- gc.mem_alloc()
Return the number of bytes of heap RAM that are allocated by Python code.
Difference to CPython
This function is MicroPython extension.
- gc.mem_free()
Return the number of bytes of heap RAM that is available for Python code to allocate, 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 -
set_threshold(), but due to different GC implementations, its signature and semantics are different.Examples
To trigger a garbage collection each time 32768 bytes of RAM have been allocated in total:
gc.threshold(32768)
To restore the default behaviour, only triggering garbage collection when out of memory:
gc.threshold(-1)
Example
>>> import gc
>>> gc.mem_free() # Gets number of bytes free in memory
8192
>>> gc.mem_alloc() # Gets number of bytes allocated in memory
1024
>>> foo = bytearray(1000) # Create a big array of data
>>> gc.mem_free() # Show that there's less memory available
7168
>>> gc.mem_alloc() # Show that there's more memory used
2048
>>> del foo # Delete the object
>>> gc.mem_free() # Show that collection hasn't run yet
7168
>>> gc.mem_alloc() # That memory is still allocated
2048
>>> gc.collect() # Manually run the collection
>>> gc.mem_free() # Now we have reclaimed that memory
8192
>>> gc.mem_alloc() # That memory is no longer allocated
1024