Registers and runs workflows and coordinates their activities,
durable deferreds, interrupts, resumes and clocks (Effect's
WorkflowEngine). Build one with workflow_engine.make_unsafe
(or use layer_memory); copy.replace(engine, poll=...) swaps an
operation.
Functions#
__init__#
__init__(register, execute, poll, interrupt, interrupt_unsafe, resume, activity_execute, deferred_result, deferred_done, schedule_clock) -> None| Parameter | Type | Description |
|---|---|---|
register | Register | |
execute | Execute | |
poll | Poll | |
interrupt | ByExecutionId | |
interrupt_unsafe | ByExecutionId | |
resume | ByExecutionId | |
activity_execute | ActivityExecute | |
deferred_result | DeferredResult | |
deferred_done | DeferredDone | |
schedule_clock | ScheduleClock |
def __init__( # noqa: PLR0917
self,
register: Register,
execute: Execute,
poll: Poll,
interrupt: ByExecutionId,
interrupt_unsafe: ByExecutionId,
resume: ByExecutionId,
activity_execute: ActivityExecute,
deferred_result: DeferredResult,
deferred_done: DeferredDone,
schedule_clock: ScheduleClock,
) -> None:
self._register = register
self._execute = execute
self._poll = poll
self._interrupt = interrupt
self._interrupt_unsafe = interrupt_unsafe
self._resume = resume
self._activity_execute = activity_execute
self._deferred_result = deferred_result
self._deferred_done = deferred_done
self._schedule_clock = schedule_clockregister#
register(workflow, execute) -> Effect[None, Never, Scope]Registers execute(payload, execution_id) as the handler of
workflow, with the services of the caller, until the Scope
closes. Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execute | Callable[[Any, str], Effect[Any, Any, Any]] |
Returns Effect[None, Never, Scope]
def register(
self,
workflow: Workflow[Any, Any, Any],
execute: Callable[[Any, str], Effect[Any, Any, Any]],
/,
) -> Effect[None, Never, Scope]:
"""Registers ``execute(payload, execution_id)`` as the handler of
``workflow``, with the services of the caller, until the ``Scope``
closes. Never fails."""
return self._register(workflow, execute)execute#
execute(workflow, /, *, execution_id, payload, discard=False, detached=False, suspended_retry_schedule=None) -> Effect[Any, Any]Runs workflow (it must be registered, else a defect) with
payload as execution_id. With discard it gives the
execution id without waiting for the result; otherwise it gives the
workflow's success or fails with its error.
A caller outside any workflow waits for the result, retrying a
suspended execution on suspended_retry_schedule (by default
exponential from 200 ms, at most 30 s apart), woken sooner when the
engine sees the result. Inside a workflow the child is interrupted
with its parent, and a child suspension suspends the parent; a child
that was interrupted is a defect for the parent. detached skips
that link and needs discard (else a defect).
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execution_id | str | |
payload | object | |
discard | bool = False | |
detached | bool = False | |
suspended_retry_schedule | Schedule[Any, Any, Any, Any] | None = None |
Returns Effect[Any, Any]
def execute(
self,
workflow: Workflow[Any, Any, Any],
/,
*,
execution_id: str,
payload: object,
discard: bool = False,
detached: bool = False,
suspended_retry_schedule: Schedule[Any, Any, Any, Any] | None = None,
) -> Effect[Any, Any]:
"""Runs ``workflow`` (it must be registered, else a defect) with
``payload`` as ``execution_id``. With ``discard`` it gives the
execution id without waiting for the result; otherwise it gives the
workflow's success or fails with its error.
A caller outside any workflow waits for the result, retrying a
suspended execution on ``suspended_retry_schedule`` (by default
exponential from 200 ms, at most 30 s apart), woken sooner when the
engine sees the result. Inside a workflow the child is interrupted
with its parent, and a child suspension suspends the parent; a child
that was interrupted is a defect for the parent. ``detached`` skips
that link and needs ``discard`` (else a defect)."""
return self._execute(
workflow,
execution_id=execution_id,
payload=payload,
discard=discard,
detached=detached,
suspended_retry_schedule=suspended_retry_schedule,
)poll#
poll[P, A, E](workflow, execution_id) -> Effect[Result[A, E] | None]The result of the execution so far (Complete or
Suspended), None when it has none. Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[P, A, E] | |
execution_id | str |
Returns Effect[Result[A, E] | None]
def poll[P, A, E](
self, workflow: Workflow[P, A, E], execution_id: str, /
) -> Effect[Result[A, E] | None]:
"""The result of the execution so far (``Complete`` or
``Suspended``), ``None`` when it has none. Never fails."""
return self._poll(workflow, execution_id)interrupt#
interrupt(workflow, execution_id) -> Effect[None]Interrupts the execution: its run is replayed to run its compensations and interrupt its child workflows. Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execution_id | str |
Returns Effect[None]
def interrupt(self, workflow: Workflow[Any, Any, Any], execution_id: str, /) -> Effect[None]:
"""Interrupts the execution: its run is replayed to run its
compensations and interrupt its child workflows. Never fails."""
return self._interrupt(workflow, execution_id)interrupt_unsafe#
interrupt_unsafe(workflow, execution_id) -> Effect[None]Interrupts the execution at once, possibly skipping its compensations and orphaning its child workflows. Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execution_id | str |
Returns Effect[None]
def interrupt_unsafe(
self, workflow: Workflow[Any, Any, Any], execution_id: str, /
) -> Effect[None]:
"""Interrupts the execution at once, possibly skipping its
compensations and orphaning its child workflows. Never fails."""
return self._interrupt_unsafe(workflow, execution_id)resume#
resume(workflow, execution_id) -> Effect[None]Replays a suspended execution. Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execution_id | str |
Returns Effect[None]
def resume(self, workflow: Workflow[Any, Any, Any], execution_id: str, /) -> Effect[None]:
"""Replays a suspended execution. Never fails."""
return self._resume(workflow, execution_id)activity_execute#
activity_execute[A, E](activity, attempt) -> Effect[Result[A, E], Never, WorkflowInstance]Runs activity (its attempt-th try) for the workflow run
in the context, or gives its stored result when it already ran.
Its failure is in the Result; the effect never fails.
| Parameter | Type | Description |
|---|---|---|
activity | Activity[A, E, Any] | |
attempt | int |
Returns Effect[Result[A, E], Never, WorkflowInstance]
def activity_execute[A, E](
self, activity: Activity[A, E, Any], attempt: int, /
) -> Effect[Result[A, E], Never, WorkflowInstance]:
"""Runs ``activity`` (its ``attempt``-th try) for the workflow run
in the context, or gives its stored result when it already ran.
Its failure is in the ``Result``; the effect never fails."""
return self._activity_execute(activity, attempt)deferred_result#
deferred_result[A, E](deferred) -> Effect[Exit[A, E] | None, Never, WorkflowInstance]The stored exit of deferred for the workflow run in the
context, None while it is not done. Never fails.
| Parameter | Type | Description |
|---|---|---|
deferred | DurableDeferred[A, E] |
Returns Effect[Exit[A, E] | None, Never, WorkflowInstance]
def deferred_result[A, E](
self, deferred: DurableDeferred[A, E], /
) -> Effect[Exit[A, E] | None, Never, WorkflowInstance]:
"""The stored exit of ``deferred`` for the workflow run in the
context, ``None`` while it is not done. Never fails."""
return self._deferred_result(deferred)deferred_done#
deferred_done[A, E](deferred, /, *, workflow_name, execution_id, deferred_name, exit) -> Effect[None]Stores exit as the result of the deferred deferred_name
of execution_id (of workflow_name), then resumes the run
waiting on it. Never fails.
| Parameter | Type | Description |
|---|---|---|
deferred | DurableDeferred[A, E] | |
workflow_name | str | |
execution_id | str | |
deferred_name | str | |
exit | Exit[A, E] |
Returns Effect[None]
def deferred_done[A, E](
self,
deferred: DurableDeferred[A, E],
/,
*,
workflow_name: str,
execution_id: str,
deferred_name: str,
exit: Exit[A, E],
) -> Effect[None]:
"""Stores ``exit`` as the result of the deferred ``deferred_name``
of ``execution_id`` (of ``workflow_name``), then resumes the run
waiting on it. Never fails."""
return self._deferred_done(
deferred,
workflow_name=workflow_name,
execution_id=execution_id,
deferred_name=deferred_name,
exit=exit,
)schedule_clock#
schedule_clock(workflow, /, *, execution_id, clock) -> Effect[None]Schedules the wake-up of clock for execution_id: when it
is due, the clock's deferred is done and the execution resumes.
Never fails.
| Parameter | Type | Description |
|---|---|---|
workflow | Workflow[Any, Any, Any] | |
execution_id | str | |
clock | DurableClock |
Returns Effect[None]
def schedule_clock(
self, workflow: Workflow[Any, Any, Any], /, *, execution_id: str, clock: DurableClock
) -> Effect[None]:
"""Schedules the wake-up of ``clock`` for ``execution_id``: when it
is due, the clock's deferred is done and the execution resumes.
Never fails."""
return self._schedule_clock(workflow, execution_id=execution_id, clock=clock)