Executing Flows
View SourceOverview
Jido.Exec runs canonical Flows through native Runic workflow state. The same
engine supports run-to-completion and step-wise execution.
Run the cells from top to bottom.
Install The Package
Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])Define Actions And A Flow
defmodule FlowExecution.Add do
use Jido.Action, name: "flow_execution_add"
@impl true
def run(%{left: left, right: right}, _context) do
{:ok, %{value: left + right}}
end
end
defmodule FlowExecution.Combine do
use Jido.Action, name: "flow_execution_combine"
@impl true
def run(%{left: left, right: right}, _context) do
{:ok, %{total: left + right}}
end
end
defmodule FlowExecution.Diamond do
use Jido.Flow, name: "flow_execution_diamond"
flow do
step "left",
action: FlowExecution.Add,
params: %{left: input(:value), right: 1}
step "right",
action: FlowExecution.Add,
params: %{left: input(:value), right: 2}
step "combine",
action: FlowExecution.Combine,
params: %{
left: result("left", :value),
right: result("right", :value)
}
output(%{result: result("combine")})
end
endRun To Completion
{:ok, %{result: %{total: 13}}} =
Jido.Exec.run(FlowExecution.Diamond, %{value: 5})Enable concurrent independent work at the call boundary.
{:ok, result} =
Jido.Exec.run(
FlowExecution.Diamond,
%{value: 5},
%{},
max_concurrency: 2
)Start Paused
{:ok, execution} =
Jido.Exec.start(
FlowExecution.Diamond,
%{value: 5},
%{},
max_concurrency: 2
)
:running = Jido.Exec.status(execution)
ready = Jido.Exec.ready(execution)ready contains small Jido.Exec.Work descriptions. Each has a component
path, kind, role, status, optional Map item index, and an opaque token. It
includes authored components and native support work.
Step One Work Unit
[work | _] = ready
{:ok, %Jido.Exec.Work{} = applied, execution} =
Jido.Exec.step(execution, work.token)
{applied.status, Jido.Exec.status(execution)}step/1 selects the first ready unit. step/2 accepts its opaque token.
A failed unit returns a Work with status: :failed. Get new tokens after
each mutation, including for work that remains ready.
Run A Wave
{:ok, applied, execution} = Jido.Exec.wave(execution)
Enum.map(applied, & &1.status)A wave runs work from the set that is ready when the call begins. A failure stops new dispatch; work already admitted can finish. The returned list contains only admitted runnables. Work that becomes ready waits for the next operation. The wave consumes one execution revision.
Continue And Read The Result
{:ok, execution} = Jido.Exec.continue(execution)
:succeeded = Jido.Exec.status(execution)
{:ok, %{result: %{total: 13}}} = Jido.Exec.result(execution)Always pass the latest Execution value. Reusing an old revision returns
Jido.Flow.Error.InvalidExecutionError before Action work starts.
Observe Failure
defmodule FlowExecution.Fail do
use Jido.Action, name: "flow_execution_fail"
@impl true
def run(_params, _context), do: {:error, :not_available}
end
defmodule FlowExecution.Failing do
use Jido.Flow, name: "flow_execution_failing"
flow do
step "fail", action: FlowExecution.Fail, params: %{}
output(%{result: result("fail")})
end
end{:error, error} = Jido.Exec.run(FlowExecution.Failing)
Exception.message(error)A failed runnable stops new dispatch after Jido applies the failure. Work that already started in the same wave can finish. When multiple wave runnables fail, the Flow error keeps a canonical failure list.
Support Work Is Visible
Map exposes FanOut, item work, FanIn, and output work. Reduce uses native Reduce and FanIn work. Subflow exposes its nested Workflow and InputBinding work. A Join can enforce explicit or inferred dependencies.
This boundary keeps one native scheduler and one graph state. Do not assume
that every Work is one authored component. Use Jido.Exec.native/1 when
you need advanced, read-only inspection of native graphs and facts.
Execution Lifetime
An Execution is caller-owned in-memory state. It is not a persistent checkpoint. It cannot resume safely after deployment or process recovery. Use a higher-level runtime for queues, persistence, retry, cancellation policy, recovery, and distributed coordination.