From c4e3a03fa53bf456e13f930bc6187f203ca77e71 Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sat, 24 Jun 2017 13:35:41 +0300
Subject: [PATCH] docs/gc: Document gc.threshold() function.

---
 docs/library/gc.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/library/gc.rst b/docs/library/gc.rst
index 94422f23e..7290efa83 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.
-- 
GitLab