Jido.Exec (Jido Action v3.0.0-beta.12)

View Source

Runs Actions, Instructions, and Flows through one public execution boundary.

run/4 validates the executable and its input, runs the requested work, validates normal output, and returns structured errors. A Flow is compiled to one native Runic workflow before execution.

{:ok, output} = Jido.Exec.run(MyApp.SendNotice, %{address: "a@example.com"})

{:ok, output} =
  Jido.Exec.run(MyApp.NoticeFlow, %{address: "a@example.com"}, %{},
    timeout: 5_000
  )

run_async/4 starts the same run-to-completion work and returns a caller-owned handle. Use await/1, await/2, handle_message/2, or cancel/1 from the process that created the handle.

Return {:ok, output, requests} to request deferred effects. Actions and Flows return the same explicit batch contract. Exec never dispatches requests. A failed complete call returns no executable batch, including effects collected before a continuation. Requests must be a proper list. See Jido.Action for the result and ordering contract.

Synchronous calls with timeout: :infinity run serial callbacks in the caller. They share its process state and cannot contain a hard self-kill. Finite-timeout and async calls use one supervised execution worker for the complete call. Serial Steps and continuations reuse that worker. Concurrent waves use bounded supervised workers. A living controller enforces deadlines and cancellation. If that controller or a direct scheduler dies abruptly, workers may continue. See the execution guide for ownership, process costs, and external resource cleanup.

Step-wise Flow execution

ready/1 returns small Jido.Exec.Work descriptions. Each value identifies one native work unit, including support work such as Join, input binding, fan-out, and fan-in. step/1, step/2, and wave/1 keep these stopping points. Jido does not hide or drain support work.

Pass a ready Work's opaque token to step/2. Tokens select one unit in one execution revision. Get new tokens after each mutation, including for work that remains ready. Step and wave results keep the input tokens and report each admitted unit's status without retaining application payloads. Use continue/1 and result/1 to get the same final result as run/4.

native/1 is the advanced, read-only view of native workflow, compilation, and ready data. Its native shapes depend on the Runic version.

The caller owns the execution lifecycle. Each successful step/2 or wave/1 call atomically consumes one execution revision. Concurrent use or reuse of an older execution returns a stale flow execution error before Jido dispatches Action work. Always pass the latest returned execution to the next operation. Execution values are not persistent checkpoints and cannot continue safely after deployment or process recovery.

Execution keeps Jido Action and Flow telemetry. Map, Reduce, and Iterate can also emit item or iteration telemetry. Native Runic support nodes do not get an artificial Jido component lifecycle.

Telemetry handlers run synchronously in the process that emits the event. Supervisor startup also uses a normal synchronous OTP call. Blocked startup or cleanup handlers can delay a timeout or cancellation response. Keep host registry functions and telemetry handlers short. No helper process isolates them.

Summary

Types

The classification result for one asynchronous owner mailbox message.

A caller-owned handle for one asynchronous run-to-completion execution.

The opaque one-shot state token shared by one asynchronous handle.

The result of an Action, Instruction, or Flow execution.

Options for run-to-completion execution.

Options for a paused Flow execution.

A local Task.Supervisor PID, registered name, or via reference.

Functions

Waits up to 5 seconds for an asynchronous execution result.

Waits for an asynchronous execution result.

Cancels a caller-owned asynchronous execution.

Continues a paused Flow execution until it reaches a terminal status.

Classifies one mailbox message for a caller-owned asynchronous execution.

Returns native data for advanced, read-only inspection.

Returns small Jido.Exec.Work descriptions of the ready units.

Returns the remaining time recorded in an execution context.

Returns the cached result of a terminal Flow execution.

Runs an executable asynchronously and immediately returns a caller-owned handle.

Returns the current Flow execution status.

Executes the first ready work unit, including support work.

Executes one ready unit selected by its opaque Jido.Exec.Work.token/0.

Executes runnables from the set that is currently ready.

Types

async_control()

@type async_control() :: %{ref: reference(), owner: pid()}

async_message_result()

@type async_message_result() ::
  {:done, exec_result()} | :ignore | {:error, Exception.t()}

The classification result for one asynchronous owner mailbox message.

async_ref()

@type async_ref() :: %{
  ref: reference(),
  pid: pid(),
  owner: pid(),
  monitor_ref: reference(),
  state: async_state()
}

A caller-owned handle for one asynchronous run-to-completion execution.

async_state()

@opaque async_state()

The opaque one-shot state token shared by one asynchronous handle.

exec_result()

@type exec_result() ::
  {:ok, term()} | {:ok, term(), Jido.Action.effects()} | {:error, Exception.t()}

The result of an Action, Instruction, or Flow execution.

run_option()

@type run_option() ::
  {:task_supervisor, task_supervisor()}
  | {:timeout, timeout()}
  | {:max_concurrency, pos_integer()}
  | {:max_continuations, non_neg_integer()}

Options for run-to-completion execution.

start_option()

@type start_option() ::
  {:task_supervisor, task_supervisor()} | {:max_concurrency, pos_integer()}

Options for a paused Flow execution.

task_supervisor()

@type task_supervisor() :: pid() | atom() | {:via, module(), term()}

A local Task.Supervisor PID, registered name, or via reference.

Functions

await(async_ref)

@spec await(async_ref()) :: exec_result()

Waits up to 5 seconds for an asynchronous execution result.

await(async_ref, timeout)

@spec await(async_ref(), timeout()) :: exec_result()

Waits for an asynchronous execution result.

A finite wait timeout cancels the running execution and returns a Jido.Exec.Error.AsyncTimeoutError. Use :infinity to wait without a caller-side limit. The timeout: option passed to run_async/4 remains the separate complete-call execution limit.

cancel(async_ref)

@spec cancel(async_ref()) :: :ok | {:error, Exception.t()}

Cancels a caller-owned asynchronous execution.

Pass the complete handle returned by run_async/4.

Cancellation stops active Action and Flow work. It does not undo side effects that already completed and it does not return a partial Flow execution value. The owner waits up to 500 milliseconds for a normal stop, then forces a stop and waits up to 500 milliseconds for its exit.

continue(execution)

@spec continue(Jido.Exec.Execution.t()) ::
  {:ok, Jido.Exec.Execution.t()} | {:error, Exception.t()}

Continues a paused Flow execution until it reaches a terminal status.

The function returns the updated execution. Use result/1 to read its cached Flow result.

handle_message(async_ref, message)

@spec handle_message(async_ref(), term()) :: async_message_result()

Classifies one mailbox message for a caller-owned asynchronous execution.

Use this function from an OTP callback such as handle_info/2. It returns {:done, result} for the handle's completion message, :ignore for an unrelated message, or {:error, error} for an invalid handle or owner.

A completion consumes the handle and removes its matching result and monitor messages. The same owner process must use run_async/4 and this function.

native(execution)

@spec native(Jido.Exec.Execution.t()) :: %{
  workflow: Runic.Workflow.t(),
  compiled: Jido.Flow.Compiled.t(),
  ready: [Runic.Workflow.Runnable.t()]
}

Returns native data for advanced, read-only inspection.

The map contains the live prepared :workflow, derived :compiled data, and native :ready runnables. Their shapes depend on the Runic version. These values can retain application data and callbacks. They are not small descriptors or a storage format. This function does not consume a revision. A native workflow changed outside Exec cannot be applied back to Execution.

ready(execution)

@spec ready(Jido.Exec.Execution.t()) :: [Jido.Exec.Work.t()]

Returns small Jido.Exec.Work descriptions of the ready units.

remaining_time(context)

@spec remaining_time(map()) :: non_neg_integer() | :infinity | nil

Returns the remaining time recorded in an execution context.

Returns non-negative milliseconds for a finite execution budget, :infinity for untimed work, or nil when no valid budget is present. An expired budget returns 0. This is a read-only observation, not a cancellation check or a guarantee that an external operation has time to finish.

Exec reserves context.__jido_exec__ for runtime metadata and adds a :deadline with an absolute monotonic time in milliseconds or :infinity. All other context fields stay unchanged. Malformed reserved metadata is rejected by execution before Action work starts.

Pass the context to nested run/4 or run_async/4 calls to preserve or shorten the budget. Subflows and continuations pass it automatically. Tasks can read the budget when given the context; no process-local state is used. Passing context does not transfer cancellation ownership or add a timer.

Step-wise execution retains its supplied context, including any deadline. Pause time therefore reduces a supplied finite budget, but does not cause automatic cancellation. Without a supplied budget, step-wise work reads :infinity. Do not persist this runtime metadata or send it to another VM.

result(execution)

@spec result(Jido.Exec.Execution.t()) :: exec_result()

Returns the cached result of a terminal Flow execution.

The function returns a validation error while the execution is still running. It does not repeat Flow output validation.

run(executable, input \\ %{}, context \\ %{}, opts \\ [])

@spec run(term(), map() | keyword() | nil, map() | keyword() | nil, [run_option()]) ::
  exec_result()

Runs an executable Jido artifact.

The task_supervisor: option accepts a local Task.Supervisor PID, name, or via route. It defaults to Jido.Exec.TaskSupervisor. Exec preserves the route through nested work and continuations. Names resolve at each task start; a PID selects one process. An unavailable supervisor is an error.

All targets accept timeout: milliseconds | :infinity. The default is :infinity. Zero returns an immediate timeout before work starts. A finite timeout covers the complete execution and terminates its worker and active child work. Supervisor startup is synchronous and can delay the response beyond this limit. Cleanup telemetry can also delay the response. The deadline is not reset between Actions or continuations. Exec does not retry.

All targets accept :max_concurrency, which defaults to 8. A value of 1 runs ready work serially. A value greater than 1 runs independent ready work concurrently, up to that limit. Map items are native Runic runnables, so the same rule applies to them. An Action does not use this option itself, but a continuation can select a Flow in the same call. An Instruction uses the option rules of its resolved target.

An Action can return {:continue, input, target}. The current executable ends, and Exec runs the target as the next executable in the same complete call. The default :max_continuations value is 256. Its valid range is 0 through 10,000. This limit and the complete-call timeout stop infinite continuation chains.

run_async(executable, input \\ %{}, context \\ %{}, opts \\ [])

@spec run_async(term(), map() | keyword() | nil, map() | keyword() | nil, [
  run_option()
]) :: async_ref()

Runs an executable asynchronously and immediately returns a caller-owned handle.

The executable can be any target accepted by run/4. The background process uses the same validation, timeout, telemetry, and result contract as run/4. Use await/2 to receive its final result, handle_message/2 in an OTP callback, or cancel/1 to stop it.

The handle is tied to the mailbox of the process that starts the execution. Only that process can wait for, handle, or cancel it. These operations are alternative one-shot terminal consumers.

Invalid routing raises Jido.Action.Error.InvalidInputError before a handle exists. Failure to start the async control task raises Jido.Exec.Error.AsyncExecutionError. Once a handle exists, failures use its normal result and message contract.

start(executable, input \\ %{}, context \\ %{}, opts \\ [])

@spec start(term(), map() | keyword() | nil, map() | keyword() | nil, [start_option()]) ::
  {:ok, Jido.Exec.Execution.t()} | {:error, Exception.t()}

Starts a paused Flow execution.

The function accepts a Flow artifact, a module that uses Jido.Flow, or an Instruction with either Flow target. It validates the Flow, input, context, and run options before it returns. The returned execution is paused before the first native Runic runnable.

:max_concurrency and the :task_supervisor reference are stored on the execution. wave/1 and continue/1 use the scheduling options. step/1 and step/2 always execute one runnable.

A paused execution has no running timeout. start/4 does not accept the :timeout option. The step-wise API also does not accept retry, deadline, asynchronous execution, cancellation, persistence, or rewind options.

status(execution)

@spec status(Jido.Exec.Execution.t()) :: :running | :succeeded | :failed

Returns the current Flow execution status.

The result is :running, :succeeded, or :failed.

step(execution)

@spec step(Jido.Exec.Execution.t()) ::
  {:ok, Jido.Exec.Work.t(), Jido.Exec.Execution.t()} | {:error, Exception.t()}

Executes the first ready work unit, including support work.

step(execution, token)

Executes one ready unit selected by its opaque Jido.Exec.Work.token/0.

Get the token from ready/1. A token is valid only in that execution revision. Invalid, stale, and foreign tokens fail before Action work starts.

A work failure is returned in the Work with status: :failed. The operation returns :ok because the result was applied to the workflow.

wave(execution)

@spec wave(Jido.Exec.Execution.t()) ::
  {:ok, [Jido.Exec.Work.t()], Jido.Exec.Execution.t()} | {:error, Exception.t()}

Executes runnables from the set that is currently ready.

Runnables that become ready during the wave wait for the next operation. The stored max_concurrency limit applies to the wave. A failed runnable stops admission of pending work. Already admitted runnables finish before Jido applies their results in the original ready order. A failure can thus return fewer runnables than the initial ready set.