pool.h File Reference

SQLite connection pool for CWIST. More...

#include <cwist/core/db/sql.h>
#include <cwist/sys/err/cwist_err.h>
#include <cjson/cJSON.h>
#include <stddef.h>

Include dependency graph for pool.h:

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

Go to the source code of this file.

Typedefs
typedef struct cwist_db_pool	cwist_db_pool_t
	Opaque database connection pool handle.

Functions
cwist_db_pool_t *	cwist_db_pool_create (const char *path, size_t max_conns)
	Create a pool of SQLite connections.
void	cwist_db_pool_destroy (cwist_db_pool_t *pool)
	Destroy the pool and close all connections.
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.
cwist_db *	cwist_db_pool_acquire (cwist_db_pool_t *pool)
	Acquire a connection from the pool. Blocks 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 connection to the pool.
size_t	cwist_db_pool_in_use (cwist_db_pool_t *pool)
	Count connections currently leased from the pool.
cwist_error_t	cwist_db_pool_exec (cwist_db_pool_t *pool, const char *sql)
	Execute a non-query using a pooled connection.
cwist_error_t	cwist_db_pool_query (cwist_db_pool_t *pool, const char *sql, cJSON **result)
	Execute a query using a pooled connection.

Detailed Description

SQLite connection pool for CWIST.

Definition in file pool.h.

Typedef Documentation

cwist_db_pool_t

typedef struct cwist_db_pool cwist_db_pool_t

Opaque database connection pool handle.

Definition at line 21 of file pool.h.

Function Documentation

cwist_db_pool_acquire()

cwist_db * cwist_db_pool_acquire

(

cwist_db_pool_t *

pool

)

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

Returns

SQLite db handle, or NULL on error.

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.

Acquire a connection, waiting at most timeout_ms milliseconds.

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 SQLite connections.

Parameters

path	SQLite database path (or ":memory:").
max_conns	Maximum number of connections (>= 1).

Returns

Pool handle, or NULL on failure.

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

)

Destroy the pool and close all connections.

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.

Begin shutdown and destroy the pool after outstanding leases return.

Unlike cwist_db_pool_destroy(), this never waits indefinitely for an orphaned checked-out connection. On timeout it leaves pool allocated, closed to new acquisitions, and safe for cwist_db_pool_release(); call this function again after the remaining leases return.

Parameters

pool	Pool to shut down.
timeout_ms	Maximum wait in milliseconds; -1 waits indefinitely.

Returns

true when the pool was destroyed, false when leases remain or the arguments are invalid.

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 non-query using a 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.

Return the number of currently checked-out connections.

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
	)

Execute a query using a 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 connection to the pool.

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().