Adding pool ctx documentation

doc/source/user_guide/pool.rst

@@ -46,7 +46,7 @@ Run a set of input files
 ------------------------
 
 You can use the pool to run a set of pre-generated input files using the
-:func:`run_batch <ansys.mapdl.core.MapdlPool.run_batch>` method. For
+:meth:`MapdlPool.run_batch <ansys.mapdl.core.MapdlPool.run_batch>` method. For
 example, this code would run the first set of 20 verification files:
 
 .. code:: pycon
@@ -63,7 +63,7 @@ Run a user function
 
 You can use the pool to run a custom user function on each MAPDL
 instance over a set of inputs. As in the example for the
-:func:`run_batch <ansys.mapdl.core.MapdlPool.run_batch>` function,
+:meth:`MapdlPool.run_batch <ansys.mapdl.core.MapdlPool.run_batch>` function,
 the following code uses a set of verification files. However, it implements
 it as a function and outputs the final routine instead of the text
 output from MAPDL.
@@ -99,11 +99,109 @@ output from MAPDL.
     pool.exit()
 
 
+Using next available instances
+------------------------------
+
+When working with many multiple instances, it might be more convenient to use
+:class:`MapdlPool <ansys.mapdl.core.pool.MapdlPool>` within a context manager.
+This can be accomplished using :meth:`MapdlPool.next() <ansys.mapdl.core.MapdlPool.next>`
+as follows:
+
+.. code:: python
+
+    with pool.next() as mapdl:
+        mapdl.prep7()
+        ...
+
+This context manager makes sure to set the instance as busy or locked while code
+is executing the block.
+Once the execution exits the context manager, the instance is set free or unlocked.
+This context manager is particularly interesting when using it with threads.
+
+.. code:: python
+
+    from ansys.mapdl.core import MapdlPool
+    from threading import Thread
+
+    loads = [1E6, 2E6, 3E6]
+    solutions = {each_load: None for each_load in loads}
+
+    pool = MapdlPool(2)
+
+    def calculate_model(mapdl, load):
+        mapdl.prep7()
+        mapdl.et(1, "SOLID5")
+        mapdl.block(0, 10, 0, 20, 0, 30)
+        mapdl.esize(10)
+        mapdl.vmesh("ALL")
+        mapdl.units("SI")  # SI - International system (m, kg, s, K).
+
+        # Define a material (nominal steel in SI)
+        mapdl.mp("EX", 1, 210e9)  # Elastic moduli in Pa (kg/(m*s**2))
+        mapdl.mp("DENS", 1, 7800)  # Density in kg/m3
+        mapdl.mp("PRXY", 1, 0.3)  # Poisson's Ratio
+
+        # Fix the left-hand side.
+        mapdl.nsel("S", "LOC", "Z", 0)
+        mapdl.d("ALL", "UX")
+        mapdl.d("ALL", "UY")
+        mapdl.d("ALL", "UZ")
+
+        mapdl.nsel("S", "LOC", "Z", 30)
+        mapdl.f("ALL", "FX", load)
+
+        mapdl.allsel()
+        mapdl.solu()
+        mapdl.antype("STATIC")
+        mapdl.solve()
+        mapdl.finish()
+
+        # Getting maximum displacement in the X direction on the top surface.
+        mapdl.nsel("S", "LOC", "Z", 30)
+        solutions[load] = mapdl.post_processing.nodal_displacement("X").max()
+
+    def threaded_function(load):
+        with pool.next() as mapdl:
+            value = calculate_model(mapdl, load)
+
+    if __name__ == "__main__":
+        threads = []
+        for load in loads:
+            t = Thread(target = threaded_function, args = [load])
+            t.start()
+            threads.append(t)
+        
+        for thread in threads:
+            thread.join()
+
+        for k, v in solutions.items():
+            print(f"Load: {k:5.2f}\tDisplacement: {v:8.6f}")
+
+
+You can also use :meth:`MapdlPool.next_available() <ansys.mapdl.core.MapdlPool.next_available>`
+to obtain on :class:`Mapdl <ansys.mapdl.core.mapdl._MapdlCore>` instance, but in that case,
+you need to manage the :meth:`Mapdl.locked <ansys.mapdl.core.mapdl._MapdlCore.locked>` lock.
+
+.. code:: python
+
+    pool = MapdlPool(4)
+
+    mapdl, i = pool.next_available(return_index=True)
+
+    mapdl.locked = True
+
+    mapdl.prep7()
+    # More code...
+    # ...
+    #
+    mapdl.locked = False # Important for the instance to be seen as available.
+
+
 Close the PyMAPDL pool
 ----------------------
 
 You can close the PyMAPDL pool with the
-:meth:`pool.exit() <ansys.mapdl.core.MapdlPool.exit>` command.
+:meth:`MapdlPool.exit() <ansys.mapdl.core.MapdlPool.exit>` command.
 
 .. code:: pycon