docs/gc: Document gc.threshold() function.

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.