# `Snakepit.ETSOwner`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.13.0/lib/snakepit/ets_owner.ex#L1)

Centralized owner of shared ETS tables used by Snakepit.

## Purpose

ETS tables are linked to the process that creates them. If a short-lived
process (like a Task) creates a table, the table is destroyed when that
process exits. This module solves that problem by acting as a long-lived
GenServer that owns all shared ETS tables for the Snakepit application.

## Managed Tables

The following tables are managed by this module:

- `:snakepit_worker_taints` - Tracks tainted workers in the crash barrier system.
  Used by `Snakepit.Worker.TaintRegistry` to prevent routing requests to
  workers that have recently crashed.

- `:snakepit_zero_copy_handles` - Stores handles for zero-copy data transfers
  (DLPack, Arrow). Used by `Snakepit.ZeroCopy` to track active handles and
  their metadata.

All tables are created with `read_concurrency: true` for optimal read
performance in concurrent scenarios.

## Lifecycle

This module is started as part of the base supervision tree (always started,
regardless of `pooling_enabled` setting). Tables are created during `init/1`
and persist for the lifetime of the application.

## Usage

Consumer modules should call `ensure_table/1` to guarantee a table exists
before accessing it:

    defp ensure_table do
      Snakepit.ETSOwner.ensure_table(:snakepit_worker_taints)
    end

The function is idempotent - calling it multiple times is safe and efficient.

## Error Handling

- Raises `ArgumentError` if an unknown table name is passed to `ensure_table/1`
- Raises `RuntimeError` if called before the Snakepit application is started

# `table_name`

```elixir
@type table_name() :: :snakepit_worker_taints | :snakepit_zero_copy_handles
```

Known ETS table names managed by this module.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `ensure_table`

```elixir
@spec ensure_table(table_name()) :: table_name()
```

Ensures the specified ETS table exists, creating it if necessary.

This function is idempotent - if the table already exists, it returns
immediately. If the table doesn't exist, it delegates creation to the
ETSOwner GenServer to ensure proper ownership.

## Parameters

- `table` - Atom name of the table. Must be one of the known tables
  registered in this module (`:snakepit_worker_taints` or
  `:snakepit_zero_copy_handles`).

## Returns

The table name atom on success.

## Raises

- `ArgumentError` - If the table name is not in the known registry
- `RuntimeError` - If ETSOwner is not running (Snakepit not started)

## Examples

    iex> Snakepit.ETSOwner.ensure_table(:snakepit_worker_taints)
    :snakepit_worker_taints

    iex> Snakepit.ETSOwner.ensure_table(:unknown_table)
    ** (ArgumentError) unknown ETS table :unknown_table

---

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