libstp.step.logic.do_while
==========================

.. py:module:: libstp.step.logic.do_while


Classes
-------

.. autoapisummary::

   libstp.step.logic.do_while.DoWhileActive


Functions
---------

.. autoapisummary::

   libstp.step.logic.do_while.do_while_active


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

.. py:class:: DoWhileActive(reference_step: libstp.step.Step, task: libstp.step.Step)

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


   Run one task step only while a reference step is still active.


   .. py:attribute:: reference_step


   .. py:attribute:: task


.. py:function:: do_while_active(reference_step: libstp.step.Step, task: libstp.step.Step)

   Run a task concurrently with a reference step, cancelling the task when the reference finishes.

   Both steps start executing at the same time. When ``reference_step``
   completes (either normally or via exception), ``task`` is immediately
   cancelled. This is useful for running a background activity (e.g.
   sensor polling, motor oscillation) only for as long as a primary
   action is running.

   If ``task`` finishes before ``reference_step``, the reference step
   continues running until it completes on its own.

   :param reference_step: The primary step whose lifetime controls the task.
                          When this step finishes, ``task`` is cancelled.
   :param task: The secondary step that runs concurrently and is cancelled
                once ``reference_step`` completes.

   :returns: A step that manages the concurrent execution.
   :rtype: DoWhileActive

   Example::

       from libstp.step.logic import do_while_active, loop_forever

       # Flash an LED while the robot drives forward
       flash_led = loop_forever(seq([
           set_digital(0, True),
           wait(0.25),
           set_digital(0, False),
           wait(0.25),
       ]))
       do_while_active(drive_forward(50), flash_led)