# `GeoGenius.Runners.Task`
[🔗](https://github.com/agoodway/geo_genius/blob/main/lib/geo_genius/runners/task.ex#L1)

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.

# `available?`

```elixir
@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`

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

# `name`

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

Returns `"task"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*