Runs an import under a Task.Supervisor.
:geo_genius starts a Task.Supervisor registered as
GeoGenius.TaskSupervisor unless a host has already configured its own
(see GeoGenius.Application). This backend uses that supervisor when a
host has configured nothing, so an asynchronous import needs zero host
configuration. A host that wants the supervisor inside its own tree
instead sets:
config :geo_genius, :task_supervisor, MyApp.TaskSupervisorwith MyApp.TaskSupervisor started under the host's own supervision tree
-- and, for a host that cares about shutdown order, listed after
MyApp.Repo there. See GeoGenius.Application's moduledoc for why that
placement matters: the library's own default supervisor sits outside the
host's tree and is stopped only after the host's own tree has already
finished shutting down, so with no configuration an import task can
outlive the host's Repo for the entire length of that shutdown. A
supervisor the host places after Repo does not have that problem --
supervisors stop children in the reverse of their start order, so a
later-listed TaskSupervisor stops before Repo does.
A configured name takes precedence over the library's own supervisor
whether or not the configured one is actually running -- a host that set
the key gets the gap named rather than silently redirected to the
library's default. enqueue/3 never falls back to a bare spawn/1, which
would provide no task-supervisor lifecycle or shutdown ordering for a host
to inspect or control.
A separate package-owned execution guardian monitors the task. If the task
dies while the Repo remains reachable, the guardian records a durable
failure with the exact claimed executor; it never restarts the task or
transfers execution. A Task does not trap exits, so it dies wherever it
happens to be when its supervisor stops and cannot clean up its staging
table. A host-owned supervisor placed after Repo lets the guardian record
that death before Repo shuts down. With the package-owned default, Repo may
already be gone by the time the dependency application's task dies, and
whole-node loss leaves no guardian alive; those cases remain stale,
operator-visible abandoned attempts. Task.Supervisor.children/1 lists
currently running task pids, though only as bare pids and, under a shared
host override, potentially mixed with unrelated tasks. Query import_run
(or GeoGenius.status/2) for actual import state.
Summary
Functions
Reports whether the resolved supervisor name is actually running.
Starts the import under the resolved Task.Supervisor and returns
immediately.
Returns "task".
Functions
@spec available?() :: boolean()
Reports whether the resolved supervisor name is actually running.
Resolved in order: config :geo_genius, :task_supervisor, then
GeoGenius.TaskSupervisor, the supervisor GeoGenius.Application starts
whenever the host has not configured one of its own. A configured but
dead name -- the host set the key and never started the child -- is
unavailable exactly like the library's own supervisor would be if
something stopped it: enqueue/3 cannot start a run under a supervisor
that is not there to accept it.
@spec enqueue(GeoGenius.Context.t(), Ecto.UUID.t(), GeoGenius.Runner.args()) :: :ok | {:error, GeoGenius.Runner.enqueue_error()}
Starts the import under the resolved Task.Supervisor and returns
immediately.
Returns {:error, {:not_enqueued, reason}} naming the configured name when
it is set but nothing is registered under it, naming
GeoGenius.TaskSupervisor in the same way should that library-started
supervisor ever not be running, or naming a live supervisor's refusal to
start the child (a host-configured :max_children cap, say). Never falls
back to an unsupervised process, and never reports :ok for a child that
was not started.
@spec name() :: String.t()
Returns "task".