C3Http.Session

Inherits: RefCounted

Holds a pool of idle HTTP connections for reuse across calls, reducing the TCP and TLS handshake cost for repeated requests to the same host.

Description

Create one C3Http.Session per logical group of requests and set it on session. A C3Http.Session is a RefCounted and is freed automatically when no C3Http.Options objects reference it.

One-off callers that leave session as null pay zero cost — a fresh connection is opened each time, as in previous versions.

Properties

Type	Name	Default
int	max_connections_per_host	6
float	idle_timeout	60.0

Methods

Returns	Signature
void	close()
void	prune()
HTTPClient	checkout(key: String)
void	checkin(key: String, client: HTTPClient)

Property Descriptions

int max_connections_per_host = 6

Maximum number of idle connections kept per unique (host, port, scheme, TLS, proxy) key. Extra connections beyond this limit are closed immediately on checkin.

float idle_timeout = 60.0

Seconds an idle connection may sit in the pool before being discarded on the next checkout attempt. Keep this shorter than the server's keep-alive timeout (nginx defaults to 75 s, so 60 s is a safe choice). Set to 0.0 to disable time-based eviction.

Method Descriptions

close

func close() -> void:

Closes all pooled connections and empties the pool. Optional — connections are also freed when the C3Http.Session goes out of scope.

prune

func prune() -> void:

Evicts all idle connections whose age exceeds idle_timeout. Useful after a network change to force fresh connections on the next call.

checkout

func checkout(key: String) -> HTTPClient:

Returns a connected, non-expired client for key, or null if none is available. Stale or disconnected entries encountered during the search are discarded.

checkin

func checkin(
    key: String,
    client: HTTPClient
) -> void:

Returns client to the pool under key. If the pool is at max_connections_per_host capacity, the oldest idle entry is closed and evicted.