GitHub

WorkflowEngineService

API reference for WorkflowEngineService.

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
ParameterTypeDescription
registerRegister
executeExecute
pollPoll
interruptByExecutionId
interrupt_unsafeByExecutionId
resumeByExecutionId
activity_executeActivityExecute
deferred_resultDeferredResult
deferred_doneDeferredDone
schedule_clockScheduleClock
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_clock

register

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.

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
executeCallable[[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).

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
execution_idstr
payloadobject
discardbool = False
detachedbool = False
suspended_retry_scheduleSchedule[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.

ParameterTypeDescription
workflowWorkflow[P, A, E]
execution_idstr

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.

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
execution_idstr

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.

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
execution_idstr

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.

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
execution_idstr

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.

ParameterTypeDescription
activityActivity[A, E, Any]
attemptint

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.

ParameterTypeDescription
deferredDurableDeferred[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.

ParameterTypeDescription
deferredDurableDeferred[A, E]
workflow_namestr
execution_idstr
deferred_namestr
exitExit[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.

ParameterTypeDescription
workflowWorkflow[Any, Any, Any]
execution_idstr
clockDurableClock

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)