Event Handling

Events are used to pass data from child tasks to their parents or other tasks. A task can emit events and other tasks can listen to these by installing an event handler or obtaining an async iterator of events. In both cases the type of event listened to can be efficiently filtered.

class yosys_mau.task_loop.TaskEvent

Base class for events emitted by tasks.

Note that the source of the event is recorded at the time of construction, not when the event is emitted. To emit an event from a different task, create the event inside a Task.as_current_task block.

property source: Task

The task that created and emitted this event.

emit()

Emit this event from the current task.

It is an error to emit an event from a task other than the one that created it. To emit events from a different task, create the event inside a Task.as_current_task block.

Return type:

None

class yosys_mau.task_loop.TaskEventStream(cursor, where)

An async iterator that yields events emitted by a task or its children.

Usually obtained by calling Task.events.

To handle events synchronously, use Task.sync_handle_events instead of this.

Parameters:

  • cursor (asyncio.Future[TaskEventCursor[T_TaskEvent]])

  • where (Callable[[T_TaskEvent], bool])

process(handler, *, wait=True)

Process events from this event stream using a background coroutine of the current task.

Parameters:

  • handler (Callable[[Self], Awaitable[None]]) – An async function that receives this event stream as argument.

  • wait (bool) – Forwarded to Task.background. If set (the default), it will prevent the current task from finishing until the stream is exhausted.

Return type:

None

handle(handler)

Handle events from this event stream using a callback function.

The callback is executed in the context of the current task. While the callback is running, the current task is prevented from finishing. Events emitted after the current task finished do not invoke the callback. Note that an async handler can block the processing of subsequent events.

Parameters:

handler (Callable[[T_TaskEvent], Awaitable[None] | None]) – An async or sync function that receives each event as argument.

Return type:

None

Built-in Events

class yosys_mau.task_loop.DebugEvent

Base class for debug events emitted by the task loop itself.

class yosys_mau.task_loop.TaskStateChange(previous_state, state)

Bases: DebugEvent

Event emitted whenever a task changes state.

Parameters:

  • previous_state (Literal['preparing', 'pending', 'running', 'waiting', 'done', 'cancelled', 'discarded', 'failed'] | None)

  • state (Literal['preparing', 'pending', 'running', 'waiting', 'done', 'cancelled', 'discarded', 'failed'])

class yosys_mau.task_loop.TaskLoopInterrupted

Bases: TaskEvent

Event emitted when the task loop is interrupted by a signal.