Executing Flows

View Source

Overview

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
end

Run 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.