step.logic.background
=====================

.. py:module:: step.logic.background

.. autoapi-nested-parse::

   Background step execution — launch steps without blocking the sequence.

   A ``background(step)`` call starts the step asynchronously and returns
   immediately so the next step in the sequence can proceed.  If a later
   foreground step needs a resource that the background step holds, the
   background step is automatically cancelled with a warning.

   Use ``wait_for_background()`` to explicitly synchronise with one or all
   background steps before continuing.



Classes
-------

.. autoapisummary::

   step.logic.background.Background
   step.logic.background.WaitForBackground


Functions
---------

.. autoapisummary::

   step.logic.background.background
   step.logic.background.wait_for_background


Module Contents
---------------

.. py:class:: Background(step: step.Step, name: Optional[str] = None)

   Bases: :py:obj:`step.Step`


   Launch a step in the background without blocking the sequence.


   .. py:method:: collected_resources() -> frozenset[str]

      Return all resources this step *and its children* require.

      Used by ``validate_no_overlap`` for static conflict detection at
      construction time.  Leaf steps don't need to override this — the
      default delegates to ``required_resources``.  Composite steps
      override to union their children's collected resources.



.. py:class:: WaitForBackground(name: Optional[str] = None)

   Bases: :py:obj:`step.Step`


   Wait for one or all background steps to complete.


.. py:function:: background(step: step.Step, name: Optional[str] = None) -> Background

   Launch a step in the background without blocking.

   Start executing *step* immediately but continue the sequence without
   waiting for it to finish.  Use ``wait_for_background()`` to
   synchronise later, or let the step run to completion on its own.

   If a later foreground step requires exclusive access to a hardware
   resource that the background step is using, the background step is
   automatically cancelled with a warning — the foreground step takes
   priority.

   Multiple background steps can run concurrently as long as they do
   not claim the same resources.

   :param step: The step to execute in the background.
   :param name: Optional identifier for later retrieval with
                ``wait_for_background``.  Re-using a name while the
                previous background step is still running logs a warning.

   :returns: A Background step that launches *step* asynchronously.

   Example::

       from raccoon.step import background, wait_for_background, seq
       from raccoon.step.servo import servo_move
       from raccoon.step.motion import drive_forward

       # Move a servo while driving — no resource conflict
       seq([
           background(servo_move(0, 1500), name="arm"),
           drive_forward(25),
           wait_for_background("arm"),
       ])


.. py:function:: wait_for_background(name: Optional[str] = None) -> WaitForBackground

   Wait for background steps to complete.

   Without arguments, wait for **all** running background steps.
   With a *name*, wait only for the background step registered under
   that name.  Returns immediately if the step has already finished
   or was preempted.

   :param name: Identifier of a specific background step to wait for.
                If ``None``, waits for every active background step.

   :returns: A WaitForBackground step.

   Example::

       from raccoon.step import background, wait_for_background, seq

       seq([
           background(long_running_step(), name="scan"),
           do_something_quick(),
           wait_for_background("scan"),
       ])