===============================================
Locking Groups of Actions to Reserve a Resource
===============================================

Locking groups of actions can be useful if you want to reserve a resource, like a liquid handler, over a set of different actions. This is commonly used to reserve a resource over a load assistant, the run method, and unload, so that other jobs do not attempt to claim the resource.

To set this up in :doc:`orchestration_python`, there are a few notable concepts:


1. Actor Reference

   Import::

       from artificial.workflows.decorators import actor_reference

   Then connect the actor reference to what has been configured in your adapter in :file:`config.yaml`::

       bravo = actor_reference('bravo', [('bravo', InstrumentActor)], 'Bravo')

2. Utilize the actor by reserving it in Orchestration Python.

   Import::

       from artificial.workflows.util import reserve

   Then reserve::

       with reserve(bravo, InstrumentActor):
           await LockingAssistants.load()
           await run_bravo_method()

Locking Example
---------------

.. code-block:: python

   from artificial.workflows.decorators import workflow, actor_reference
   from artificial.workflows.util import reserve
   from stubs.stubs_assistants import LockingAssistants
   from stubs.stubs_actions import run_bravo_method, run_i7_method

   bravo = actor_reference('bravo', [('bravo', InstrumentActor)], 'Bravo')
   i7 = actor_reference('i7', [('i7', InstrumentActor)], 'Beckman Biomek i7')

   @workflow('Locking', 'wf_locking', 'lab_c9eae09e-ceed-46d1-8390-87ff7dd8586d')
   async def locking() -> None:

      # This locks the bravo resource, over the execution of all three of these actions
      with reserve(bravo, InstrumentActor):
         await LockingAssistants.load()
         await run_bravo_method()
         await LockingAssistants.unload()

      with reserve(i7, InstrumentActor ):
         await LockingAssistants.load()
         await run_i7_method()
         await LockingAssistants.unload()