CouncilEx.Supervisor (CouncilEx v0.1.0)

Copy Markdown View Source

Optional DynamicSupervisor wrapper for grouping council runs.

CouncilEx itself does not ship a bundled supervisor — CouncilEx.start/3 spawns runners unsupervised (GenServer.start/3 semantics) and CouncilEx.start_link/3 links them to the caller. Use this module only when you want group management of multiple runs:

  • Tenant isolation — one supervisor per tenant; bulk-cancel via Supervisor.stop/1 or terminate_all/1.
  • Visibility — which_children/1 enumerates in-flight runs.
  • Lifecycle ownership — runs survive caller exit, die when the supervisor exits.

Children are :temporary (no restart on crash) — re-running a partially-completed council from scratch wastes tokens and produces weird state.

Setup

Place an instance in your supervision tree:

children = [
  {CouncilEx.Supervisor, name: MyApp.RunSup}
]

Then start runs against it:

{:ok, pid} =
  CouncilEx.Supervisor.start_link(MyApp.RunSup, council, input)

# Fetch the run_id when needed (e.g. for PubSub subscribe across
# processes, persistence as a durable handle):
run_id = CouncilEx.RunServer.run_id(pid)

Pass any CouncilEx.start/3 opt (e.g. :registry, :recorder, :verbose) — they're forwarded to the runner.

Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

start_link(opts)

Start the supervisor. Pass :name (required for named lookup).

start_link(supervisor, council, input, opts \\ [])

Start a run as a child of this supervisor. The runner is linked to the supervisor (not the caller).

terminate_all(supervisor)

Terminate every child runner under supervisor. Synchronous.

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(opts)

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

Start the supervisor. Pass :name (required for named lookup).

start_link(supervisor, council, input, opts \\ [])

@spec start_link(
  Supervisor.supervisor(),
  module() | CouncilEx.DynamicCouncil.t(),
  term(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Start a run as a child of this supervisor. The runner is linked to the supervisor (not the caller).

Returns {:ok, pid}. Fetch the run_id from the pid via CouncilEx.RunServer.run_id/1 if needed, or supply your own with the :run_id opt. Validation, options, and PubSub semantics match CouncilEx.start/3.

terminate_all(supervisor)

@spec terminate_all(Supervisor.supervisor()) :: :ok

Terminate every child runner under supervisor. Synchronous.

Each runner receives :shutdown. Subscribers monitoring a runner pid see :DOWN. Use this for tenant teardown.