GeoGenius.Runners.Task (geo_genius v0.2.0)

Copy Markdown View Source

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

with 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

available?()

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

enqueue(context, run_id, args)

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.

name()

@spec name() :: String.t()

Returns "task".