bpo-31356: Add context manager to temporarily disable GC (GH-4224)

1 files changed, 28 insertions, 0 deletions

diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 153d8fb..92240c7 100644
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -33,6 +33,34 @@ The :mod:`gc` module provides the following functions:
    Disable automatic garbage collection.
 
 
+.. class:: ensure_disabled()
+
+   Return a context manager object that disables the garbage collector and reenables the previous
+   state upon completion of the block. This is basically equivalent to::
+
+     from gc import enable, disable, isenabled
+
+     @contextmanager
+     def ensure_disabled():
+         was_enabled_previously = isenabled()
+         gc.disable()
+         yield
+         if was_enabled_previously:
+             gc.enable()
+
+   And lets you write code like this::
+
+     with ensure_disabled():
+         run_some_timing()
+
+     with ensure_disabled():
+         # do_something_that_has_real_time_guarantees
+         # such as a pair trade, robotic braking, etc
+
+   without needing to explicitly enable and disable the garbage collector yourself.
+   This context manager is implemented in C to assure atomicity, thread safety and speed.
+
+
 .. function:: isenabled()
 
    Returns true if automatic collection is enabled.