Document @cython.with_gil (GH-5522)

docs/src/userguide/nogil.rst

@@ -42,7 +42,7 @@ You can mark a whole function (either a Cython function or an :ref:`external fun
 .. tabs::
 
     .. group-tab:: Pure Python
-    
+
         .. code-block:: python
 
             @cython.nogil
@@ -52,9 +52,9 @@ You can mark a whole function (either a Cython function or an :ref:`external fun
             ...
 
     .. group-tab:: Cython
-    
+
         .. code-block:: cython
-    
+
             cdef void some_func() noexcept nogil:
                 ....
 
@@ -77,37 +77,63 @@ To actually release the GIL you can use context managers
 .. tabs::
 
     .. group-tab:: Pure Python
-    
+
         .. code-block:: python
-        
+
             with cython.nogil:
-                ...  # some code that runs without the GIL
+                ...              # some code that runs without the GIL
                 with cython.gil:
-                    ...  # some code that runs with the GIL
-                ...  # some more code without the GIL
-            
+                    ...          # some code that runs with the GIL
+                ...              # some more code without the GIL
+
     .. group-tab:: Cython
-    
+
         .. code-block:: cython
-    
+
             with nogil:
-                ...  # some code that runs without the GIL
+                ...      # some code that runs without the GIL
                 with gil:
                     ...  # some code that runs with the GIL
-                ...  # some more code without the GIL
-            
+                ...      # some more code without the GIL
+
 The ``with gil`` block is a useful trick to allow a small
 chunk of Python code or Python object processing inside a non-GIL block. Try not to use it
 too much since there is a cost to waiting for and acquiring the GIL, and because these
 blocks cannot run in parallel since all executions require the same lock.
 
-A function may be marked as ``with gil`` to ensure that the
-GIL is acquired immediately then calling it. This is currently a Cython-only
-feature (no equivalent syntax exists in pure-Python mode)::
+A function may be marked as ``with gil`` or decorated with ``@cython.with_gil``  to ensure that the
+GIL is acquired immediately when calling it.
+
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.with_gil
+            @cython.cfunc
+            def some_func() -> cython.int
+                ...
+
+            with cython.nogil:
+                ...          # some code that runs without the GIL
+                some_func()  # some_func() will internally acquire the GIL
+                ...          # some code that runs without the GIL
+            some_func()      # GIL is already held hence the function does not need to acquire the GIL
+
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef int some_func() with gil:
+                ...
+
+            with nogil:
+                ...          # some code that runs without the GIL
+                some_func()  # some_func() will internally acquire the GIL
+                ...          # some code that runs without the GIL
+            some_func()      # GIL is already held hence the function does not need to acquire the GIL
 
-  cdef int some_func() with gil:
-      ...
-      
 Conditionally acquiring the GIL
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -117,19 +143,19 @@ This is most often used when working with :ref:`fusedtypes`
 .. tabs::
 
     .. group-tab:: Pure Python
-    
+
         .. code-block:: python
-    
+
             with cython.nogil(some_type is not object):
                 ...  # some code that runs without the GIL, unless we're processing objects
-            
+
     .. group-tab:: Cython
-    
+
         .. code-block:: cython
-    
+
             with nogil(some_type is not object):
                 ...  # some code that runs without the GIL, unless we're processing objects
-      
+
 Exceptions and the GIL
 ----------------------