diff options
| -rw-r--r-- | docs/library/gc.rst | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/docs/library/gc.rst b/docs/library/gc.rst index 94422f23eb..7290efa835 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -38,3 +38,27 @@ Functions :class: attention This function is MicroPython extension. + +.. function:: threshold([amount]) + + Set or query additional GC allocation threshold. Normally, GC is + triggered when new allocation cannot be satisfied, i.e. on out of + memory (OOM) condition. If this function is called, in addition to + OOM, GC will be triggered each time after *amount* of bytes has been + allocated (in total, since the previous time such amount of bytes + had been allocated). *amount* is usually specified as less than the + full heap size, with the intention to trigger GC earlier than the + heap will be exhausted, and in the hope that early GC will prevent + excessive memory fragmentation. This is a heuristic measure, effect + of which will vary from an application to application, as well as + the optimal value of *amount* parameter. + + Calling the function without argument will return current value of + the threshold. Value of -1 means a disabled allocation threshold. + + .. admonition:: Difference to CPython + :class: attention + + This function is MicroPython extension. CPython has a similar + function - ``set_threshold()``, but due to different GC + implementations, its signature and semantics are different. |