hackney_pool (hackney v2.0.0)

View Source

Pool of connection processes.

This module manages hackney_conn processes in a pool. Instead of storing raw sockets, it tracks connection process pids. Idle timeout is handled by the connection processes themselves (gen_statem state_timeout).

Summary

Functions

checkin(PoolInfo, Pid)

Return a connection process to the pool.

checkout(Host, Port, Transport, Options)

Checkout a connection process from the pool. Returns {ok, PoolInfo, Pid} where Pid is a hackney_conn process.

checkout_h2(Host, Port, Transport, Options)

Get an existing HTTP/2 connection for a host/port, or 'none' if not available. HTTP/2 connections are shared (multiplexed) across callers.

checkout_h3(Host, Port, Transport, Options)

Get an existing HTTP/3 connection for a host/port, or 'none' if not available. HTTP/3 connections are shared (multiplexed) across callers via QUIC streams.

child_spec(Name, Options0)

return a child spec suitable for embedding your pool in the supervisor

code_change(OldVsn, State, Extra)
count(Name)

get the number of connections in the pool

count(Name, Key)

get the number of connections in the pool for {Host, Port, Transport}

find_pool(Name)
get_stats(Pool)
handle_call(_, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
host_stats(PoolName, Host, Port)

Get per-host connection statistics. Returns a proplist with: - active: number of active requests (from load_regulation) - in_use: connections checked out from pool - free: connections available in pool

init(_)
max_connections(Name)

get max pool size

notify(Pool, Msg)
prewarm(PoolName, Host, Port)

Prewarm connections to a host (default count from pool settings) Starts the pool if it doesn't exist.

prewarm(PoolName, Host, Port, Count)

Prewarm a specific number of connections to a host Starts the pool if it doesn't exist.

register_h2(Host, Port, Transport, Pid, Options)

Register an HTTP/2 connection in the pool for sharing. Called after ALPN negotiation confirms HTTP/2.

register_h3(Host, Port, Transport, Pid, Options)

Register an HTTP/3 connection in the pool for sharing. Called after QUIC connection is established with HTTP/3.

set_max_connections(Name, NewSize)

change the pool size

set_timeout(Name, NewTimeout)

change the connection timeout

start()
start_link(Name, Options0)
start_pool(Name, Options)

start a pool

stop_pool(Name)

stop a pool

terminate(Reason, State)
timeout(Name)

get timeout

to_pool_name(Name)
unregister_h2(Pid, Options)

Remove an HTTP/2 connection from the pool (e.g., on GOAWAY).

unregister_h2_all()

Remove all HTTP/2 connections from the default pool. Used for testing to ensure clean state between tests.

unregister_h3(Pid, Options)

Remove an HTTP/3 connection from the pool (e.g., on connection close).

Functions

checkin(PoolInfo, Pid)

-spec checkin(PoolInfo :: term(), Pid :: pid()) -> ok.

Return a connection process to the pool.

checkout(Host, Port, Transport, Options)

-spec checkout(Host :: string(), Port :: non_neg_integer(), Transport :: module(), Options :: list()) ->
                  {ok, term(), pid()} | {error, term()}.

Checkout a connection process from the pool. Returns {ok, PoolInfo, Pid} where Pid is a hackney_conn process.

checkout_h2(Host, Port, Transport, Options)

-spec checkout_h2(Host :: string(), Port :: non_neg_integer(), Transport :: module(), Options :: list()) ->
                     {ok, pid()} | none.

Get an existing HTTP/2 connection for a host/port, or 'none' if not available. HTTP/2 connections are shared (multiplexed) across callers.

checkout_h3(Host, Port, Transport, Options)

-spec checkout_h3(Host :: string(), Port :: non_neg_integer(), Transport :: module(), Options :: list()) ->
                     {ok, pid()} | none.

Get an existing HTTP/3 connection for a host/port, or 'none' if not available. HTTP/3 connections are shared (multiplexed) across callers via QUIC streams.

child_spec(Name, Options0)

return a child spec suitable for embedding your pool in the supervisor

code_change(OldVsn, State, Extra)

count(Name)

get the number of connections in the pool

count(Name, Key)

get the number of connections in the pool for {Host, Port, Transport}

find_pool(Name)

get_stats(Pool)

handle_call(_, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

host_stats(PoolName, Host, Port)

-spec host_stats(atom(), string() | binary(), inet:port_number()) -> [{atom(), non_neg_integer()}].

Get per-host connection statistics. Returns a proplist with: - active: number of active requests (from load_regulation) - in_use: connections checked out from pool - free: connections available in pool

init(_)

max_connections(Name)

get max pool size

notify(Pool, Msg)

prewarm(PoolName, Host, Port)

-spec prewarm(atom(), string() | binary(), inet:port_number()) -> ok.

Prewarm connections to a host (default count from pool settings) Starts the pool if it doesn't exist.

prewarm(PoolName, Host, Port, Count)

-spec prewarm(atom(), string() | binary(), inet:port_number(), non_neg_integer()) -> ok.

Prewarm a specific number of connections to a host Starts the pool if it doesn't exist.

register_h2(Host, Port, Transport, Pid, Options)

-spec register_h2(Host :: string(),
                  Port :: non_neg_integer(),
                  Transport :: module(),
                  Pid :: pid(),
                  Options :: list()) ->
                     ok.

Register an HTTP/2 connection in the pool for sharing. Called after ALPN negotiation confirms HTTP/2.

register_h3(Host, Port, Transport, Pid, Options)

-spec register_h3(Host :: string(),
                  Port :: non_neg_integer(),
                  Transport :: module(),
                  Pid :: pid(),
                  Options :: list()) ->
                     ok.

Register an HTTP/3 connection in the pool for sharing. Called after QUIC connection is established with HTTP/3.

set_max_connections(Name, NewSize)

change the pool size

set_timeout(Name, NewTimeout)

change the connection timeout

start()

start_link(Name, Options0)

start_pool(Name, Options)

start a pool

stop_pool(Name)

stop a pool

terminate(Reason, State)

timeout(Name)

get timeout

to_pool_name(Name)

unregister_h2(Pid, Options)

-spec unregister_h2(Pid :: pid(), Options :: list()) -> ok.

Remove an HTTP/2 connection from the pool (e.g., on GOAWAY).

unregister_h2_all()

-spec unregister_h2_all() -> ok.

Remove all HTTP/2 connections from the default pool. Used for testing to ensure clean state between tests.

unregister_h3(Pid, Options)

-spec unregister_h3(Pid :: pid(), Options :: list()) -> ok.

Remove an HTTP/3 connection from the pool (e.g., on connection close).