client_pool.h File Reference

HTTP client connection pool. More...

#include <keel/allocator.h>
#include <keel/client.h>
#include <keel/error.h>
#include <keel/event_ctx.h>
#include <keel/tls.h>
#include <stdint.h>

Include dependency graph for client_pool.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlClientPoolConfig
struct	KlClientPoolConn
	Acquired connection handle. More...
struct	KlClientPoolEntry
	Pool entry (internal, stored in flat array). More...
struct	KlClientPool

Macros
#define	KL_CPOOL_DEFAULT_CAPACITY   32
	Default pool capacity.
#define	KL_CPOOL_DEFAULT_MAX_PER_HOST   4
	Default max idle connections per host.
#define	KL_CPOOL_DEFAULT_IDLE_MS   60000
	Default idle timeout (ms).

Typedefs
typedef struct KlClientPool	KlClientPool
typedef struct KlClientPoolEntry	KlClientPoolEntry
	Pool entry (internal, stored in flat array).

Functions
int	kl_cpool_init (KlClientPool *pool, const KlClientPoolConfig *cfg, KlAllocator *alloc, KlEventCtx *ev_ctx)
	Initialize a connection pool.
void	kl_cpool_free (KlClientPool *pool)
	Free all pool resources (closes all idle connections).
int	kl_cpool_acquire (KlClientPool *pool, const char *host, int port, int is_tls, const char *proxy_host, int proxy_port, KlClientPoolConn *conn)
	Try to acquire an idle connection from the pool.
int	kl_cpool_release (KlClientPool *pool, KlClientPoolConn *conn, const char *host, int port, int is_tls, const char *proxy_host, int proxy_port)
	Return a connection to the pool for reuse.
void	kl_cpool_discard (KlClientPool *pool, KlClientPoolConn *conn)
	Close and discard a connection (not returned to pool).
int	kl_cpool_evict_expired (KlClientPool *pool)
	Evict expired idle connections (for sync-only pools without timers).
int	kl_cpool_idle_count (const KlClientPool *pool)
	Count of idle connections in the pool.
int	kl_cpool_host_count (const KlClientPool *pool, const char *host, int port, int is_tls, const char *proxy_host, int proxy_port)
	Count idle connections for a specific host tuple.
int	kl_client_request_pooled (KlClientPool *pool, KlAllocator *alloc, const KlClientConfig *cfg, const char *method, const char *url, const KlClientHeader *headers, int num_headers, const char *body, size_t body_len, KlClientResponse *resp)
	Synchronous HTTP request with connection pooling.
KlClient *	kl_client_start_pooled (KlClientPool *pool, KlEventCtx *ev_ctx, KlAllocator *alloc, const KlClientConfig *cfg, const char *method, const char *url, const KlClientHeader *headers, int num_headers, const char *body, size_t body_len, KlClientDoneFn on_done, void *user_data)
	Asynchronous HTTP request with connection pooling.

Detailed Description

HTTP client connection pool.

Caches idle TCP+TLS connections keyed by (host, port, is_tls), enabling HTTP keep-alive reuse across requests. Opt-in: pass a KlClientPool to the pooled request variants.

Pool sizes are small (32-128), so entries use a flat array with linear scan — cache-friendly and simpler than a hash map.

Macro Definition Documentation

KL_CPOOL_DEFAULT_CAPACITY

#define KL_CPOOL_DEFAULT_CAPACITY   32

Default pool capacity.

KL_CPOOL_DEFAULT_MAX_PER_HOST

#define KL_CPOOL_DEFAULT_MAX_PER_HOST   4

Default max idle connections per host.

KL_CPOOL_DEFAULT_IDLE_MS

#define KL_CPOOL_DEFAULT_IDLE_MS   60000

Default idle timeout (ms).

60 seconds

Typedef Documentation

KlClientPool

typedef struct KlClientPool KlClientPool

KlClientPoolEntry

typedef struct KlClientPoolEntry KlClientPoolEntry

Pool entry (internal, stored in flat array).

Function Documentation

kl_cpool_init()

int kl_cpool_init	(	KlClientPool *	pool,
		const KlClientPoolConfig *	cfg,
		KlAllocator *	alloc,
		KlEventCtx *	ev_ctx
	)

Initialize a connection pool.

Parameters

pool	Pool to initialize (caller-owned storage).
cfg	Config (NULL for defaults).
alloc	Allocator (borrowed — must outlive pool).
ev_ctx	Event context for idle timers (NULL = manual eviction).

Returns

0 on success, -1 on error.

kl_cpool_free()

void kl_cpool_free

(

KlClientPool *

pool

)

Free all pool resources (closes all idle connections).

kl_cpool_acquire()

int kl_cpool_acquire	(	KlClientPool *	pool,
		const char *	host,
		int	port,
		int	is_tls,
		const char *	proxy_host,
		int	proxy_port,
		KlClientPoolConn *	conn
	)

Try to acquire an idle connection from the pool.

Parameters

pool	Connection pool.
host	Target hostname.
port	Target port.
is_tls	1 for TLS, 0 for plaintext.
proxy_host	Proxy hostname (NULL = direct connection).
proxy_port	Proxy port (0 = direct connection).
conn	Output: populated on hit.

Returns

0 = hit (conn populated), 1 = miss, -1 = error.

kl_cpool_release()

int kl_cpool_release	(	KlClientPool *	pool,
		KlClientPoolConn *	conn,
		const char *	host,
		int	port,
		int	is_tls,
		const char *	proxy_host,
		int	proxy_port
	)

Return a connection to the pool for reuse.

Returns

0 on success, -1 on error (connection discarded).

kl_cpool_discard()

void kl_cpool_discard	(	KlClientPool *	pool,
		KlClientPoolConn *	conn
	)

Close and discard a connection (not returned to pool).

kl_cpool_evict_expired()

int kl_cpool_evict_expired

(

KlClientPool *

pool

)

Evict expired idle connections (for sync-only pools without timers).

Returns

Number of connections evicted.

kl_cpool_idle_count()

int kl_cpool_idle_count

(

const KlClientPool *

pool

)

Count of idle connections in the pool.

kl_cpool_host_count()

int kl_cpool_host_count	(	const KlClientPool *	pool,
		const char *	host,
		int	port,
		int	is_tls,
		const char *	proxy_host,
		int	proxy_port
	)

Count idle connections for a specific host tuple.

kl_client_request_pooled()

int kl_client_request_pooled	(	KlClientPool *	pool,
		KlAllocator *	alloc,
		const KlClientConfig *	cfg,
		const char *	method,
		const char *	url,
		const KlClientHeader *	headers,
		int	num_headers,
		const char *	body,
		size_t	body_len,
		KlClientResponse *	resp
	)

Synchronous HTTP request with connection pooling.

Same as kl_client_request, but reuses connections from the pool. The pool must have been initialized with kl_cpool_init.

kl_client_start_pooled()

KlClient * kl_client_start_pooled	(	KlClientPool *	pool,
		KlEventCtx *	ev_ctx,
		KlAllocator *	alloc,
		const KlClientConfig *	cfg,
		const char *	method,
		const char *	url,
		const KlClientHeader *	headers,
		int	num_headers,
		const char *	body,
		size_t	body_len,
		KlClientDoneFn	on_done,
		void *	user_data
	)

Asynchronous HTTP request with connection pooling.

Same as kl_client_start, but reuses connections from the pool. On completion, the connection is returned to the pool unless the server sent Connection: close.