# `SuperCache.EtsHolder`
[🔗](https://github.com/ohhi-vn/super_cache/blob/main/lib/storage/ets_holder.ex#L1)

GenServer owner for ETS tables managed by SuperCache.

This process owns the lifecycle of all ETS tables used for caching.
Tables are created, tracked, and deleted through this GenServer so that:

- Tables are automatically deleted when the owning process terminates.
- The table list is tracked in state for clean shutdown.
- Creation respects the global `:key_pos` and `:table_type` configuration.

## Lifecycle

1. `start_link/1` starts the GenServer under a given name.
2. `new_table/2` creates a new ETS table with the configured options.
3. `delete_table/2` removes a specific table.
4. On shutdown, `terminate/2` deletes all tracked tables to free memory.

## Configuration

Tables are created with the following options:
- `:keypos` — derived from `Config.get_config(:key_pos) + 1` (ETS is 1-based)
- `:table_type` — from `Config.get_config(:table_type)` (`:set`, `:bag`, etc.)
- `:public` — accessible by any process
- `:named_table` — addressable by atom name
- `{:write_concurrency, true}` — optimised for concurrent writes
- `{:read_concurrency, true}` — optimised for concurrent reads
- `{:decentralized_counters, true}` — reduces contention on counter updates

## Example

    {:ok, pid} = SuperCache.EtsHolder.start_link(:my_ets_owner)
    SuperCache.EtsHolder.new_table(:my_ets_owner, :my_cache_table)
    :ets.insert(:my_cache_table, {:key, "value"})
    SuperCache.EtsHolder.stop(:my_ets_owner)

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clean`

```elixir
@spec clean(atom(), atom()) :: true
```

Clears all records from a specific ETS table without deleting it.

Returns `true` on success.

# `clean_all`

```elixir
@spec clean_all(atom()) :: :ok
```

Clears all records from all tracked ETS tables.

Tables are not deleted — only their contents are removed.

# `delete_table`

```elixir
@spec delete_table(atom(), atom()) :: :ok
```

Deletes a specific ETS table tracked by this GenServer.

The table is removed from ETS and from the internal tracking list.
No-op if the table is not found.

# `new_table`

```elixir
@spec new_table(atom(), atom()) :: :ok
```

Creates a new named ETS table owned by this GenServer.

The table is configured according to the current `:key_pos` and
`:table_type` settings in `SuperCache.Config`.

## Examples

    SuperCache.EtsHolder.new_table(:my_owner, :users_cache)
    # => :ok

# `start_link`

```elixir
@spec start_link(atom()) :: :ignore | {:error, any()} | {:ok, pid()}
```

Starts the EtsHolder GenServer under the given `name`.

The process enters hibernation when idle to reduce memory footprint.

# `stop`

```elixir
@spec stop(atom() | pid() | {atom(), any()} | {:via, atom(), any()}) :: :ok
```

Stops the EtsHolder GenServer and deletes all owned ETS tables.

The `terminate/2` callback ensures all tracked tables are removed
before the process exits.

---

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