Jido.Exec.Async (Jido Action v2.0.0)

View Source

Handles asynchronous execution of Actions using Task.Supervisor.

This module provides the core async implementation for Jido.Exec, managing task supervision, cleanup, and async lifecycle.

Summary

Types

action()
async_ref()
context()
exec_error()
exec_error_dir()
exec_result()
exec_success()
exec_success_dir()
params()
run_opts()

Functions

await(async_ref)

Waits for the result of an asynchronous Action execution.

await(async_ref, timeout)

Awaits the completion of an asynchronous Action with a custom timeout.

cancel(async_ref)

Cancels a running asynchronous Action execution.

start(action, params \\ %{}, context \\ %{}, opts \\ [])

Starts an asynchronous Action execution.

Types

action()

@type action() :: module()

async_ref()

@type async_ref() :: %{
  :ref => reference(),
  :pid => pid(),
  optional(:owner) => pid(),
  optional(:monitor_ref) => reference()
}

context()

@type context() :: map()

exec_error()

@type exec_error() :: {:error, Exception.t()}

exec_error_dir()

@type exec_error_dir() :: {:error, Exception.t(), any()}

exec_result()

@type exec_result() ::
  exec_success() | exec_success_dir() | exec_error() | exec_error_dir()

exec_success()

@type exec_success() :: {:ok, map()}

exec_success_dir()

@type exec_success_dir() :: {:ok, map(), any()}

params()

@type params() :: map()

run_opts()

@type run_opts() :: [timeout: non_neg_integer(), jido: atom()]

Functions

await(async_ref)

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

Waits for the result of an asynchronous Action execution.

Parameters

  • async_ref: The reference returned by start/4.
  • timeout: Maximum time (in ms) to wait for the result (default: 5000).

Returns

  • {:ok, result} if the Action executes successfully.
  • {:error, reason} if an error occurs during execution or if the action times out.

await(async_ref, timeout)

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

Awaits the completion of an asynchronous Action with a custom timeout.

Parameters

  • async_ref: The async reference returned by start/4.
  • timeout: Maximum time to wait in milliseconds.

Returns

  • {:ok, result} if the Action completes successfully.
  • {:error, reason} if an error occurs or timeout is reached.

cancel(async_ref)

@spec cancel(async_ref() | pid()) :: :ok | exec_error()

Cancels a running asynchronous Action execution.

Parameters

  • async_ref: The reference returned by start/4, or just the PID of the process to cancel.

Returns

  • :ok if the cancellation was successful.
  • {:error, reason} if the cancellation failed or the input was invalid.

start(action, params \\ %{}, context \\ %{}, opts \\ [])

@spec start(action(), params(), context(), run_opts()) :: async_ref()

Starts an asynchronous Action execution.

This function creates a supervised task that calls back to Jido.Exec.run/4 to ensure feature consistency across sync and async execution paths.

Parameters

  • action: The module implementing the Action behavior.
  • params: A map of input parameters for the Action.
  • context: A map providing additional context for the Action execution.
  • opts: Options controlling the execution (same as Jido.Exec.run/4).
    • :jido - Optional instance name for isolation. Routes execution through instance-scoped supervisors.

Returns

An async_ref map containing:

  • :ref - A unique reference for this async action.
  • :pid - The PID of the process executing the Action.
  • :monitor_ref - Monitor reference used for deterministic cleanup.