macula_peer_connection_pool (macula v0.20.5)

Peer Connection Pool - Manages pooled QUIC connections to remote peers.

Problem: Creating a new QUIC connection per message adds ~50-200ms latency. Solution: Pool connections and reuse them for subsequent messages.

Design: - ETS-based connection pool for O(1) lookups - LRU eviction when pool is full - Automatic connection health monitoring - Configurable pool size and idle timeout

Expected improvement: 1.5-2x latency reduction for repeated messaging.

Summary

Functions

get_connected_peers()

Get list of peer IDs with active connections. Returns list of peer IDs that have pooled connections.

get_connection(Endpoint)

Get a connection to an endpoint (from pool or create new). Returns {ok, Connection, Stream} or {error, Reason}.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

invalidate(Endpoint)

Invalidate (remove) a connection from the pool. Called when a connection fails or is no longer valid.

put(PeerId, Connection)

Put a connection directly into the pool (NAT system API). Used by connection upgrade to store successfully upgraded direct connections.

return_connection(Endpoint, _)

Return a connection to the pool for reuse.

start_link()

Start the connection pool with default options.

start_link(Opts)

Start the connection pool with options. Options: - max_connections: Maximum pooled connections (default: 100) - idle_timeout_ms: Idle connection timeout (default: 60000)

stats()

Get pool statistics.

terminate(Reason, State)