pool.c File Reference

Bounded SQLite pool with O(1) lease bookkeeping. More...

#include <cwist/core/db/pool.h>
#include <cwist/core/mem/alloc.h>
#include <pthread.h>
#include <stdatomic.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Include dependency graph for pool.c:

Go to the source code of this file.

Macros
#define	_POSIX_C_SOURCE   200809L

Functions
cwist_db_pool_t *	cwist_db_pool_create (const char *path, size_t max_conns)
	Create a pool of max_conns SQLite connections to path.
cwist_db *	cwist_db_pool_acquire (cwist_db_pool_t *pool)
	Lease a pooled connection, blocking indefinitely until one is available.
cwist_db *	cwist_db_pool_acquire_timeout (cwist_db_pool_t *pool, int timeout_ms)
	Lease a pooled connection, waiting at most timeout_ms.
void	cwist_db_pool_release (cwist_db_pool_t *pool, cwist_db *conn)
	Return a leased connection to the pool and wake one waiting acquirer.
size_t	cwist_db_pool_in_use (cwist_db_pool_t *pool)
	Count connections currently leased from the pool.
bool	cwist_db_pool_destroy_timeout (cwist_db_pool_t *pool, int timeout_ms)
	Close a pool, waiting up to timeout_ms for leased connections.
void	cwist_db_pool_destroy (cwist_db_pool_t *pool)
	Close a pool, blocking until all leased connections are released.
cwist_error_t	cwist_db_pool_exec (cwist_db_pool_t *pool, const char *sql)
	Execute a SQL statement on a leased pooled connection.
cwist_error_t	cwist_db_pool_query (cwist_db_pool_t *pool, const char *sql, cJSON **result)
	Run a query on a leased pooled connection.

Detailed Description

Bounded SQLite pool with O(1) lease bookkeeping.

Definition in file pool.c.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 2 of file pool.c.

Function Documentation

cwist_db_pool_acquire()

cwist_db * cwist_db_pool_acquire

(

cwist_db_pool_t *

pool

)

Lease a pooled connection, blocking indefinitely until one is available.

Acquire a connection from the pool. Blocks until one is available.

Parameters

pool	Pool to lease from; must not be NULL.

Returns

Leased connection to pass to cwist_db_pool_release(), or NULL if the pool is NULL or closing. Thread-safe; the caller must not use the connection after releasing it.

Definition at line 157 of file pool.c.

Referenced by cwist_db_pool_exec(), and cwist_db_pool_query().

cwist_db_pool_acquire_timeout()

cwist_db * cwist_db_pool_acquire_timeout	(	cwist_db_pool_t *	pool,
		int	timeout_ms
	)

Lease a pooled connection, waiting at most timeout_ms.

Parameters

pool	Pool to lease from; must not be NULL.
timeout_ms	Maximum wait in milliseconds; must be >= 0.

Returns

Leased connection to pass to cwist_db_pool_release(), or NULL on invalid arguments, on timeout, or if the pool is closing. Thread-safe.

Definition at line 171 of file pool.c.

cwist_db_pool_create()

cwist_db_pool_t * cwist_db_pool_create	(	const char *	path,
		size_t	max_conns
	)

Create a pool of max_conns SQLite connections to path.

Create a pool of SQLite connections.

Parameters

path	Database path, or ":memory:" for a shared in-memory database.
max_conns	Maximum number of pooled connections; must be > 0.

Returns

New pool on success, or NULL on invalid arguments or any allocation/open failure. On success all connections start idle. Thread-safe.

Definition at line 93 of file pool.c.

References cwist_alloc(), cwist_alloc_array(), cwist_db_close(), cwist_db_open(), cwist_error_dispose(), cwist_free(), and cwist_strdup().

Referenced by cwist_app_use_db_pool().

cwist_db_pool_destroy()

void cwist_db_pool_destroy

(

cwist_db_pool_t *

pool

)

Close a pool, blocking until all leased connections are released.

Destroy the pool and close all connections.

Parameters

pool	Pool to destroy; no-op if NULL. Equivalent to cwist_db_pool_destroy_timeout(pool, -1).

Definition at line 256 of file pool.c.

References cwist_db_pool_destroy_timeout().

Referenced by cwist_app_destroy(), and cwist_app_use_db_pool().

cwist_db_pool_destroy_timeout()

bool cwist_db_pool_destroy_timeout	(	cwist_db_pool_t *	pool,
		int	timeout_ms
	)

Close a pool, waiting up to timeout_ms for leased connections.

Parameters

pool	Pool to destroy; must not be NULL.
timeout_ms	Wait limit in milliseconds, or -1 to wait indefinitely for all connections to be released.

Return values

true	All connections were released and the pool (and every connection) was closed and freed.
false	The wait timed out with connections still leased; the pool is left alive and closing, so further acquires fail and the caller must retry the destroy. Thread-safe.

Definition at line 222 of file pool.c.

References cwist_db_close(), and cwist_free().

Referenced by cwist_db_pool_destroy().

cwist_db_pool_exec()

cwist_error_t cwist_db_pool_exec	(	cwist_db_pool_t *	pool,
		const char *	sql
	)

Execute a SQL statement on a leased pooled connection.

Execute a non-query using a pooled connection.

Parameters

pool	Pool to run the statement on.
sql	SQL statement to execute.

Returns

Execution result, or an INT16 error with code -1 if no connection could be acquired. The caller owns the result.

Definition at line 265 of file pool.c.

References cwist_db_exec(), cwist_db_pool_acquire(), and cwist_db_pool_release().

cwist_db_pool_in_use()

size_t cwist_db_pool_in_use

(

cwist_db_pool_t *

pool

)

Count connections currently leased from the pool.

Parameters

pool	Pool to inspect.

Returns

Number of connections in use, or 0 if pool is NULL. Thread-safe.

Definition at line 206 of file pool.c.

References count.

cwist_db_pool_query()

cwist_error_t cwist_db_pool_query	(	cwist_db_pool_t *	pool,
		const char *	sql,
		cJSON **	result
	)

Run a query on a leased pooled connection.

Execute a query using a pooled connection.

Parameters

pool	Pool to run the query on.
sql	SQL query to execute.
result	Output JSON result written by the query; caller owns and must free it.

Returns

Query result, or an INT16 error with code -1 if no connection could be acquired. The connection is released back to the pool before returning.

Definition at line 279 of file pool.c.

References cwist_db_pool_acquire(), cwist_db_pool_release(), and cwist_db_query().

cwist_db_pool_release()

void cwist_db_pool_release	(	cwist_db_pool_t *	pool,
		cwist_db *	conn
	)

Return a leased connection to the pool and wake one waiting acquirer.

Return a connection to the pool.

Parameters

pool	Pool that owns the connection.
conn	Connection previously returned by an acquire call; must belong to pool and still be leased. Invalid or already-released connections are ignored. Thread-safe.

Definition at line 189 of file pool.c.

References cwist_db::pool_slot.

Referenced by cwist_db_pool_exec(), and cwist_db_pool_query().