# `Snakepit.Pool.Registry`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.13.0/lib/snakepit/pool/registry.ex#L1)

Registry for pool worker processes.

This is a thin wrapper around Elixir's Registry that provides:
- Consistent naming for worker processes
- Easy migration path to distributed registry (Horde)
- Helper functions for worker lookup

## Canonical Metadata

All workers store a metadata map containing the following canonical keys:

* `:worker_module` – module that owns the worker implementation (usually `Snakepit.GRPCWorker`)
* `:pool_name` – atom name of the logical pool (e.g. `:default`)
* `:pool_identifier` – optional human-friendly identifier used in docs/metrics
* `:adapter_module` – adapter used to launch the Python worker

Higher-level helpers (pool, diagnostics, worker profiles) should prefer
`Snakepit.Pool.Registry.fetch_worker/1` so these keys stay authoritative.

# `child_spec`

Returns the child spec for the registry.

# `fetch_worker`

Returns `{pid, metadata}` for a registered worker.

# `get_worker_id_by_pid`

Get worker_id from PID for O(1) lookups in :DOWN messages.

# `get_worker_metadata`

Returns only the metadata for a worker.

# `get_worker_pid`

Gets the PID for a worker ID.

# `list_workers`

Lists all registered worker IDs.

# `metadata_keys`

Returns the list of canonical metadata keys maintained for each worker.

# `put_metadata`

Adds or updates metadata for a registered worker.

Accepts maps to keep metadata consistent across callers. When `Registry`
has `nil` metadata (the default when using `:via` tuples), this function
replaces it with the provided map. Future updates merge with the existing map.

Returns `:ok` on success or `{:error, :not_registered}` if the worker has
not been registered yet (best-effort semantics).

# `register_worker`

Register a worker with metadata for O(1) reverse lookups.
This is only used for manual registration - workers started with via_tuple are already registered.

# `via_tuple`

Returns a via tuple for registering/looking up a worker process.

## Examples

    iex> Snakepit.Pool.Registry.via_tuple("worker_123")
    {:via, Registry, {Snakepit.Pool.Registry, "worker_123"}}

# `worker_count`

Counts the number of registered workers.

# `worker_exists?`

Checks if a worker is registered.

---

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