Alpha

These pages are built from turborel-c’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Pools

Pools

NAME

trl_pool, trl_pool_config, trl_connector, trl_pool_config_default, trl_pool_new, trl_pool_of_settings, trl_pool_hold, trl_pool_get, trl_pool_release, trl_pool_counts, trl_pool_free: a bounded set of connections a program's threads share.

SYNOPSIS

#include <turborel/turborel.h>

#define TRL_POOL_MAX 10
#define TRL_POOL_IDLE_TIMEOUT_MS 600000U
#define TRL_POOL_MAX_LIFETIME_MS 3600000U
#define TRL_POOL_WAIT_MS 30000U
#define TRL_POOL_RESET_MOST_STATEMENTS 256U

typedef struct trl_pool_config {
    size_t max;
    size_t max_idle;
    uint32_t idle_timeout_ms;
    uint32_t max_lifetime_ms;
    uint32_t wait_ms;
    bool check;
    const char *const *reset;
    size_t reset_count;
} trl_pool_config;

typedef trl_status (*trl_connector)(void *context, trl_conn **out);

trl_pool_config trl_pool_config_default(void);
trl_status trl_pool_new(trl_connector connect, void *context, const trl_pool_config *config, trl_pool **out);
trl_status trl_pool_of_settings(const trl_settings *settings, const trl_pool_config *config, trl_pool **out);
trl_pool *trl_pool_hold(trl_pool *pool);
trl_status trl_pool_get(trl_pool *pool, trl_conn **out);
void trl_pool_release(trl_pool *pool, trl_conn *conn);
void trl_pool_counts(trl_pool *pool, size_t *made, size_t *idle);
void trl_pool_free(trl_pool *pool);

DESCRIPTION

A pool keeps a bounded set of connections that a program's threads share [CLIENT Pools]. trl_pool_new makes one of the connections connect makes, logged in, each handed context, as several threads may call it at once; trl_pool_of_settings one of the connections trl_settings_connect() makes of settings, which must last as long as the pool. Each copies config, its statements too; null is trl_pool_config_default()'s:

Field What it says Default
max The most connections made at once, handed out and idle 10
max_idle The most kept idle 10
idle_timeout_ms How long one may stay idle; 0, as long as it lives 10 minutes
max_lifetime_ms How long one lives from when it was made; 0, without limit 1 hour
wait_ms How long trl_pool_get waits for one to come back 30 seconds
check Whether an idle connection is checked to answer before it is handed out yes
reset, reset_count Statements run as each comes back, after the pool's own none

trl_pool_hold gives another part of the program a hold of the same pool, each hold freed by trl_pool_free; the last frees the pool, closing each idle connection. Every connection handed out must be given back first. A pool's functions may be called from any thread at once (RULES.md D11); the pool starts no thread, and each wait is the waiting thread's.

trl_pool_get hands out an idle connection that answers, or makes one while fewer than max are made, or waits for one to come back, at most wait_ms. One idle past idle_timeout_ms, past its life, or that does not answer its check is closed as trl_pool_get meets it, and another taken or made. The check is Ping where the server grants it, which the server answers without a worker; else ROLLBACK, which a session outside a transaction completes doing nothing. Each wait of a check or a reset is bounded by 30 seconds, or the connection's read timeout if shorter.

trl_pool_release gives a connection back, reset to the session it logged in with, so no borrower sees another's. Where the server grants it, the protocol's Reset ends the session's transaction, prepared statements, cursors, temporary tables and settings in one request and keeps its user; autocommit is off, then reset's statements run. Of a server that grants neither Ping nor Reset, the reset is one pipeline: ROLLBACK, each statement the connection prepared closed and destroyed, SET SESSION AUTHORIZATION and SET SCHEMA of its login's user, SET TIME ZONE LOCAL, then reset's statements; a statement already destroyed is no failure, and a setting a borrower changed by SET stays as it set it unless reset sets it back. A connection is closed rather than kept if it is lost, if its reset fails, if it has lived its time, if more than TRL_POOL_RESET_MOST_STATEMENTS of its statements would have to be destroyed, or if max_idle are idle already. A connection not of the pool is closed.

trl_pool_counts gives how many connections the pool has made, handed out and idle, and how many are idle; either pointer may be null.

ERRORS

trl_pool_new and trl_pool_of_settings: TRL_INVALID_ARGUMENT of a null pointer, a max of 0, or a reset_count without reset; TRL_NO_MEMORY.

trl_pool_get: TRL_INVALID_ARGUMENT of a null pointer; TRL_NO_MEMORY, nothing made; TRL_FAILED, with a connection holding why, the caller's to free: SQLSTATE 08001, SQLCODE -919, if no connection came back within wait_ms, or the failure of making one, as connect or the settings gave it.

EXAMPLES

Pipelines and Pools.