Arrea.Leader (Arrea v1.0.0)

Leader GenServer that coordinates parallel execution.

The Leader manages worker processes, coordinates task distribution, and emits events to subscribers. Workers are started via Arrea.WorkerSupervisor (DynamicSupervisor) to keep them within the OTP supervision tree.

The Leader also performs periodic cleanup of old batches (every 60s) to prevent memory leaks.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

execute(commands, opts \\ [])

Executes a list of commands or functions in parallel.

get_state()

Returns the current internal state of the Leader.

notify_event(event)

Broadcasts an event to all subscribers.

start_link(opts \\ [])

Starts the Leader as a GenServer with name Elixir.Arrea.Leader.

subscribe()

Subscribes the caller PID to Leader events.

unsubscribe()

Unsubscribes the caller PID.

Types

t()

@type t() :: %Arrea.Leader{
  batches: map(),
  max_workers: non_neg_integer(),
  stats: map(),
  subscribers: MapSet.t(),
  workers: map()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

execute(commands, opts \\ [])

@spec execute(
  [String.t() | function()],
  keyword()
) ::
  {:ok, String.t()}
  | {:ok, String.t(), %{started: non_neg_integer(), failed: non_neg_integer()}}
  | {:error, term()}

Executes a list of commands or functions in parallel.

Returns {:ok, batch_id} when all workers start successfully. Returns {:ok, batch_id, %{started: n, failed: m}} when some workers fail to start. Returns {:error, {:all_workers_failed, n}} when all workers fail. Returns {:error, {:too_many_commands, count, max}} when the list exceeds the limit.

Subscribe to Leader events to track progress. Each element in commands can be a shell command binary or a zero-arity function.

Options

:workers — Maximum parallel workers (default: 4)
:timeout — Timeout per worker in ms (default: 30_000)
:log — Enable worker logging (default: false)
:policy — Policy map for error handling
:max_workers — Maximum commands per batch (default: 100)

get_state()

@spec get_state() :: map()

Returns the current internal state of the Leader.

notify_event(event)

@spec notify_event(map()) :: :ok

Broadcasts an event to all subscribers.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the Leader as a GenServer with name Elixir.Arrea.Leader.

Options

:max_workers — Maximum number of workers (default: 100)

unsubscribe()

@spec unsubscribe() :: :ok

Unsubscribes the caller PID.