Snakepit.ETSOwner (Snakepit v0.13.0)

Copy Markdown View Source

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

Summary

Types

table_name()

Known ETS table names managed by this module.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

ensure_table(table)

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

Types

table_name()

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

Known ETS table names managed by this module.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

ensure_table(table)

@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