Raxol.
View Source
Generic connection pooling implementation for external services.
Provides connection pooling and health checking for any external service connections (HTTP, SSH, Database, etc).
Features
- Configurable pool size limits
- Transient overflow connections: up to
max_overflowextra connections are opened when the pool is empty and disconnected on checkin - Connection health checking
- Metrics and monitoring
The pool never queues callers. When every pooled and overflow connection is
checked out, checkout/2 and transaction/3 return {:error, :timeout}
immediately (counted in metrics.timeouts); retrying is up to the caller.
Usage
{:ok, _pid} =
ConnectionPool.start_link(
name: :api_pool,
pool_size: 10,
max_overflow: 5,
connect_fn: &MyApp.API.connect/0,
disconnect_fn: &MyApp.API.disconnect/1
)
ConnectionPool.transaction(:api_pool, fn conn ->
# Use connection
end)Summary
Functions
Returns a connection to the pool.
Checks out a connection from the pool.
Returns a specification to start this module under a supervisor.
Gets pool statistics.
Executes a function with a connection from the pool.
Types
@type connection() :: term()
@type pool_name() :: atom()
@type pool_opts() :: [ pool_size: pos_integer(), max_overflow: non_neg_integer(), timeout: pos_integer(), idle_timeout: pos_integer(), health_check_interval: pos_integer(), connect_fn: (-> {:ok, connection()} | {:error, term()}), disconnect_fn: (connection() -> :ok), health_check_fn: (connection() -> boolean()) ]
Functions
@spec checkin(pool_name(), connection()) :: :ok
Returns a connection to the pool.
@spec checkout(pool_name(), timeout()) :: {:ok, connection()} | {:error, term()}
Checks out a connection from the pool.
The connection belongs to the calling process until checkin/2; if that
process exits first, the pool takes the connection back.
Does not wait for a connection: when the pool and its overflow are
exhausted this returns {:error, :timeout} at once. timeout only bounds
the call to the pool process.
Returns a specification to start this module under a supervisor.
See Supervisor.
Gets pool statistics.
@spec transaction(pool_name(), (connection() -> result), timeout()) :: result | {:error, term()} when result: term()
Executes a function with a connection from the pool.
The function runs in the calling process, never inside the pool, so a slow or hung callback holds only its own connection. The connection is checked back in when the function returns or raises; if the caller dies instead, the pool reclaims it through its monitor on the caller.