step.background_manager
=======================

.. py:module:: step.background_manager

.. autoapi-nested-parse::

   Background step manager — tracks running background tasks and handles preemption.

   When a foreground step requires a resource held by a background step, the
   background step is cancelled (preempted) with a warning instead of raising
   ``ResourceConflictError``.  The manager also logs when background steps
   complete, fail, or get cancelled.



Attributes
----------

.. autoapisummary::

   step.background_manager.logger


Classes
-------

.. autoapisummary::

   step.background_manager.BackgroundManager


Functions
---------

.. autoapisummary::

   step.background_manager.get_background_manager


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

.. py:data:: logger

.. py:class:: BackgroundManager

   Track background step tasks and handle resource preemption.

   Attached to the robot instance as ``robot._background_manager``.


   .. py:method:: register(task: asyncio.Task[None], label: str, name: Optional[str], resources: frozenset[str]) -> None

      Register a background task for tracking and preemption.



   .. py:method:: preempt_conflicts(resources: frozenset[str], holder_label: str) -> None
      :async:


      Cancel background tasks whose resources overlap with *resources*.

      After cancellation, awaits cleanup so released resources are
      available for immediate acquisition.



   .. py:method:: wait_all() -> None
      :async:


      Wait for all running background tasks to complete.



   .. py:method:: wait_for_name(name: str) -> None
      :async:


      Wait for a specific named background task to complete.



   .. py:method:: cancel_all() -> None
      :async:


      Cancel all running background tasks and await cleanup.

      Called at mission boundaries and during shutdown to prevent
      orphaned tasks from leaking or triggering asyncio warnings.



   .. py:property:: active_count
      :type: int


      Number of background tasks still running.


.. py:function:: get_background_manager(robot: object) -> BackgroundManager

   Get or create the ``BackgroundManager`` attached to *robot*.