Add conditional GILStatNode usage to documentation

2 files changed, 48 insertions, 0 deletions

diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst
index b3e0546ea..9e55d0c22 100644
--- a/docs/src/userguide/external_C_code.rst
+++ b/docs/src/userguide/external_C_code.rst
@@ -580,6 +580,26 @@ The GIL may also be acquired through the ``with gil`` statement::
     with gil:
         <execute this block with the GIL acquired>
 
+.. _gil_conditional:
+
+Conditional Acquiring / Releasing the GIL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Sometimes it is helpful to use a condition to decide whether to run a
+certain piece of code with or without the GIL. This code would run anyway,
+the difference is whether the GIL will be held or released.
+The condition must be constant (at compile time).
+
+This could be useful for profiling, debugging, performance testing, and
+for fused types (see :ref:`fused_gil_conditional`).::
+
+    DEF FREE_GIL = True
+
+    with nogil(FREE_GIL):
+        <code to be executed with the GIL released>
+
+        with gil(False):
+           <GIL is still released>
+
 Declaring a function as callable without the GIL
 --------------------------------------------------
 
diff --git a/docs/src/userguide/fusedtypes.rst b/docs/src/userguide/fusedtypes.rst
index b50bb0efd..d91b3ef91 100644
--- a/docs/src/userguide/fusedtypes.rst
+++ b/docs/src/userguide/fusedtypes.rst
@@ -249,6 +249,34 @@ to figure out whether a specialization is part of another set of types
         if bunch_of_types in string_t:
             print("s is a string!")
 
+.. _fused_gil_conditional:
+
+Conditional GIL Acquiring / Releasing
+=====================================
+
+Acquiring and releasing the GIL can be controlled by a condition
+which is known at compile time (see :ref:`_gil_conditional`).
+
+This is most useful when combined with fused types.
+A fused type function may have to handle both cython native types
+(e.g. cython.int or cython.double) and python types (e.g. object or bytes).
+Conditional Acquiring / Releasing the GIL provides a method for running
+the same piece of code either with the GIL released (for cython native types)
+and with the GIL held (for python types).::
+
+    cimport cython
+
+    ctypedef fused double_or_object:
+        cython.double
+        object
+
+    def increment(double_or_object x):
+        with nogil(double_or_object is cython.double):
+            # Same code handles both cython.double (GIL is released)
+            # and python object (GIL is not released).
+            x = x + 1
+        return x
+
 __signatures__
 ==============