step.logic.background

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

Background	Launch a step in the background without blocking the sequence.
WaitForBackground	Wait for one or all background steps to complete.

Functions

background(→ Background)	Launch a step in the background without blocking.
wait_for_background(→ WaitForBackground)	Wait for background steps to complete.

Module Contents

class step.logic.background.Background(step: step.Step, name: str | None = None)

Bases: step.Step

Launch a step in the background without blocking the sequence.

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.

class step.logic.background.WaitForBackground(name: str | None = None)

Bases: step.Step

Wait for one or all background steps to complete.

step.logic.background.background(step: step.Step, name: str | None = 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.

Parameters:

• step – The step to execute in the background.

• 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"),
])

step.logic.background.wait_for_background(name: str | None = 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.

Parameters:

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"),
])