Task Management¶

See the task loop overview for general information about the task loop.

yosys_mau.task_loop.run_task_loop(on_run, *, handle_sigint=True)¶

Run the task loop.

Parameters:

on_run (Callable[[], None | Awaitable[None]]) – The function (async or sync) to run in the context of the task loop’s root task.
handle_sigint (bool) – Whether to handle SIGINT (Ctrl+C) by cancelling the root task (recursively cancelling all child tasks).

Return type:

None

yosys_mau.task_loop.current_task()¶

Return the currently active task.

Raises:: TaskLoopError – if no task is currently active
Return type:: Task

class yosys_mau.task_loop.Task(on_run=None, *, on_prepare=None, name=None)¶

Base class for all tasks.

To customize the functionality performed by a task, either declare a subclass of Task overriding the methods starting with on_ or use the on_run and on_prepare arguments of the constructor.

The constructor creates a new task as child task of the current task and schedule it to run in the current ask loop.

Parameters:

on_run (Callable[[Self], Awaitable[None] | None] | Callable[[], Awaitable[None] | None] | None) – The function to call when the task is run. Specifying this is an alternative to subclassing Task and overriding on_run.
on_prepare (Callable[[Self], Awaitable[None] | None] | Callable[[], Awaitable[None] | None] | None) – The function to call when the task is prepared. Specifying this is an alternative to subclassing Task and overriding on_prepare.
name (str | None)

__init__(on_run=None, *, on_prepare=None, name=None)¶

The constructor creates a new task as child task of the current task and schedule it to run in the current ask loop.

Parameters:

on_run (Callable[[Self], Awaitable[None] | None] | Callable[[], None | Awaitable[None]] | None) – The function to call when the task is run. Specifying this is an alternative to subclassing Task and overriding on_run.
on_prepare (Callable[[Self], Awaitable[None] | None] | Callable[[], None | Awaitable[None]] | None) – The function to call when the task is prepared. Specifying this is an alternative to subclassing Task and overriding on_prepare.
name (str | None)

__getitem__(object)¶

Wraps the given object in a proxy that performs all attribute accesses as if they were done with this task as current task.

This is primarily intended to be used with task_context objects.

Parameters:: object (T)
Return type:: T

property use_lease: bool¶: Whether the task should obtain a lease from the job server before running.

property parent: Task | None¶: The parent task of this task, or None if this is the root task.

property state: Literal['preparing', 'pending', 'running', 'waiting', 'done', 'cancelled', 'discarded', 'failed']¶: The current state of the task.

Todo

diagram of the possible state transitions

property path: str¶

The path of this task in the task tree.

Lists the names of the path from the containing top-level task to this task, separated by dots.

discard: bool¶

If set to True, the task will be discarded (automatically cancelled) when the last of the tasks depending on it finishes (by failure or cancellation).

Defaults to True.

restart_on_new_children: bool¶

If set to True, new children can be added to the task even after it successfully finished. When that happens the task is restarted, i.e. its state is set to pending again.

Defaults to False.

property name: str¶

Name of this task.

By default the class name is used, if necessary made unique among sibling tasks by appending a number.

Subclasses can assign a more meaningful name in their constructor.

depends_on(task)¶

Parameters:: task (Task)
Return type:: None

set_error_handler(task, handler)¶

A registered error handler stops this task from automatically failing (or becoming cancelled) when a child or dependency fails (or is cancelled).

Parameters:

task (Task | None) – The task to register the handler for. If None, the handler is registered as a fallback.
handler (Callable[[BaseException], None]) – The handler to call when the task fails or is cancelled. The handler is invoked as a background coroutine in the context of this task. The failed task can be recovered from the TaskAborted exception.

Return type:

None

handle_error(handler)¶

Calling task.handle_error(handler) is equivalent to current_task().set_error_handler(task, handler).

Parameters:: handler (Callable[[BaseException], None])
Return type:: None

configure_task()¶

Invoked on construction with the task set as current task.

Can be used to override initialization in subclasses.

async on_prepare()¶

Actions to perform right after the task is created, before scheduling it to run.

Can be used to add dependencies or change other task properties.

Scheduling the task is delated until this async method returns.

This executes with self as the current task.

Return type:: None

async on_run()¶

Actions to perform when the task is running.

This executes with self as the current task.

For the task to successfully finish, this async method must return, but child tasks can delay this further.

Return type:: None

property started: None¶: Awaitable that resolves when the task has started running.

property finished: None¶

Awaitable that resolves when the task has finished running.

This includes successful completion, cancellations and failure.

property is_finished: bool¶

Whether the task has finished running.

This includes successful completion, cancellations and failure.

property is_done: bool¶: Whether the task has finished running successfully.

property is_aborted: bool¶: Indicates that the task failed or was cancelled.

cancel()¶

Cancel the task.

This will also cancel all pending children as well as tasks that depend on this one and do not explicitly handle cancellation of their dependencies (with the exception of the current task).

Return type:: None

on_cancel()¶

Actions to perform when the task is cancelled.

This runs when the task is cancelled (either directly or via a parent), but not when a dependency was cancelled. See on_cleanup for an alternative that runs in all cases.

on_cleanup()¶

Actions to perform after the task finished.

This includes successful completion, cancellations and failure.

background(target, *, wait=False, error_handler=False)¶

Run a background coroutine in the context of this task.

The coroutine will execute with the current task set to this task. When the task fails or is cancelled, the background coroutine will be cancelled as well.

Parameters:

target (Callable[[], None | Awaitable[None]]) – The coroutine to run.
wait (bool) – Whether to wait for the background coroutine to finish before letting the task finish.
error_handler (bool) – Whether the background coroutine is an error handler. Without setting this, it is an error to install a background handler for a finished task.

Returns:

The asyncio task (not a task loop task) that runs the background coroutine. Can be used to cancel the background coroutine.

Return type:

Task[None]

events(event_type, where=None)¶

Return an async iterator that yields events emitted by this task or its children.

Parameters:

event_type (type[T_TaskEvent]) – The type of events to yield, use TaskEvent to yield all events.
where (Callable[[T_TaskEvent], bool] | None) – A predicate that filters the events to yield.

Return type:

TaskEventStream[T_TaskEvent]

Note that using event_type is more efficient than a where predicate that uses isinstance.

sync_handle_events(event_type, handler)¶

The synchronous handler will be called before the emit call of the event returns. The handler itself runs in the context of the current task during registration.

Parameters:

event_type (type[T_TaskEvent]) – The type of events to handle, use TaskEvent to handle all events.
handler (Callable[[T_TaskEvent], None]) – The handler to call for each event.

Returns:

A callable that can be called to unregister the handler.

Return type:

Callable[[], None]

as_current_task()¶

Returns a context manager that temporarily overrides the current task.

This is safe to use with concurrently executing tasks as each execution context has its own current task.

Return type:: ContextManager[None]

block_finishing()¶

Returns a context manager that blocks the task from finishing.

This is useful in in background coroutines that do not have wait set, but temporarily need to prevent the task from finishing.

Return type:: Iterator[None]

class yosys_mau.task_loop.TaskGroup(on_run=None, *, on_prepare=None, name=None)¶

A task used to group child tasks.

This is normal Task initialized with discard set to False and restart_on_new_children

The constructor creates a new task as child task of the current task and schedule it to run in the current ask loop.

Parameters:

on_run (Callable[[Self], Awaitable[None] | None] | Callable[[], Awaitable[None] | None] | None) – The function to call when the task is run. Specifying this is an alternative to subclassing Task and overriding on_run.
on_prepare (Callable[[Self], Awaitable[None] | None] | Callable[[], Awaitable[None] | None] | None) – The function to call when the task is prepared. Specifying this is an alternative to subclassing Task and overriding on_prepare.
name (str | None)