libstp.step.timing.do_until_checkpoint
======================================

.. py:module:: libstp.step.timing.do_until_checkpoint


Classes
-------

.. autoapisummary::

   libstp.step.timing.do_until_checkpoint.DoUntilCheckpoint


Functions
---------

.. autoapisummary::

   libstp.step.timing.do_until_checkpoint.do_until_checkpoint


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

.. py:class:: DoUntilCheckpoint(checkpoint: float, step)

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


   Run one child step until the robot synchronizer reaches a checkpoint.


   .. py:attribute:: checkpoint


   .. py:attribute:: step


   .. py:method:: run_step(robot: GenericRobot) -> None
      :async:


      Record the wrapper step, then execute the child until the checkpoint.



.. py:function:: do_until_checkpoint(checkpoint: float, step) -> DoUntilCheckpoint

   Run a step until a mission-relative time checkpoint, then cancel it.

   Starts executing ``step`` immediately and cancels it when the robot's
   global synchronizer clock reaches ``checkpoint`` seconds since mission
   start. If the step finishes before the checkpoint, execution continues
   without waiting. This is useful for time-boxing actions within a timed
   Botball run (e.g. "search for objects, but stop at T=45s no matter what").

   Prerequisites:
       The robot must have a ``synchronizer`` configured. The synchronizer
       clock starts when the mission begins.

   :param checkpoint: The mission-relative deadline (in seconds) at which
                      ``step`` will be cancelled.
   :param step: The step to run. Will be cancelled if still active when the
                checkpoint time is reached.

   :returns: A step that manages the time-boxed execution.
   :rtype: DoUntilCheckpoint

   Example::

       from libstp.step.timing import do_until_checkpoint
       from libstp.step.logic import loop_forever

       # Search for objects until T=45s, then move on
       search = loop_forever(seq([
           scan_for_object(),
           drive_forward(10),
       ]))
       seq([
           do_until_checkpoint(45.0, search),
           drive_to_start(),
       ])