Minimal in-tree Redis client (RESP2) with connection pooling. More...

#include <cwist/sys/err/cwist_err.h>
#include <stddef.h>

Include dependency graph for cwist_redis.h:

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

Classes
struct	cwist_redis_reply

Typedefs
typedef struct cwist_redis	cwist_redis_t
	Single Redis connection handle.

typedef struct cwist_redis_pool	cwist_redis_pool_t
	Redis connection pool handle.

typedef void(*	cwist_redis_msg_cb) (const char channel, const char message, void *ctx)
	Pub/sub message callback.

typedef struct cwist_redis_reply	cwist_redis_reply_t

Functions
cwist_redis_t *	cwist_redis_connect (const char *host, int port)
	Open a TCP connection to a Redis server.

void	cwist_redis_close (cwist_redis_t *r)
	Close a Redis connection.

cwist_error_t	cwist_redis_command (cwist_redis_t r, const char cmd, char **out)
	Execute a raw Redis command and return the bulk reply.

cwist_error_t	cwist_redis_command_argv (cwist_redis_t r, size_t argc, const void const argv, const size_t argv_lens, char *out, size_t out_len)

cwist_error_t	cwist_redis_auth (cwist_redis_t r, const char username, const char *password)

cwist_error_t	cwist_redis_select (cwist_redis_t *r, unsigned int database)

cwist_error_t	cwist_redis_command_argv_reply (cwist_redis_t r, size_t argc, const void const argv, const size_t argv_lens, cwist_redis_reply_t **reply)

void	cwist_redis_reply_free (cwist_redis_reply_t *reply)

cwist_error_t	cwist_redis_subscribe (cwist_redis_t r, const char channels, cwist_redis_msg_cb cb, void ctx)
	Subscribe to channels on a dedicated connection.

cwist_redis_pool_t *	cwist_redis_pool_create (const char *host, int port, size_t max_conns)
	Create a Redis connection pool.

void	cwist_redis_pool_destroy (cwist_redis_pool_t *pool)
	Destroy the pool and close all connections.

cwist_error_t	cwist_redis_pool_command_argv_reply_timeout (cwist_redis_pool_t pool, size_t argc, const void const argv, const size_t argv_lens, unsigned timeout_ms, cwist_redis_reply_t **reply)
	Run one binary-safe pooled command under a single deadline.

Detailed Description

Minimal in-tree Redis client (RESP2) with connection pooling.

Definition in file cwist_redis.h.

Typedef Documentation

◆ cwist_redis_msg_cb

typedef void(* cwist_redis_msg_cb) (const char *channel, const char *message, void *ctx)

Pub/sub message callback.

Definition at line 29 of file cwist_redis.h.

◆ cwist_redis_pool_t

typedef struct cwist_redis_pool cwist_redis_pool_t

Redis connection pool handle.

Definition at line 24 of file cwist_redis.h.

◆ cwist_redis_reply_t

typedef struct cwist_redis_reply cwist_redis_reply_t

Parsed RESP2 reply tree.

Supported since v3.8. Returned by cwist_redis_command_argv_reply(). type is the RESP type byte: '+', '-', ':', '$', '*'. For '-', str holds the error text and the command reports failure. For ':' and '$', str is the textual value (always NUL-terminated; use len for exact bulk length) and integer holds the parsed number. For '*', element/elements hold children.

◆ cwist_redis_t

typedef struct cwist_redis cwist_redis_t

Single Redis connection handle.

Definition at line 19 of file cwist_redis.h.

Function Documentation

◆ cwist_redis_auth()

cwist_error_t cwist_redis_auth	(	cwist_redis_t *	r,
		const char *	username,
		const char *	password
	)

Authenticate/select a logical Redis database on this connection.

Warning: AUTH credentials are sent over plaintext TCP (RESP has no encryption by itself). Only use this over loopback, a trusted private network, or behind a TLS-terminating proxy (stunnel/spiped) in front of Redis.

Authenticate against the server with ACL-style (username, password) or legacy (password-only) AUTH.

Parameters

r	Connection handle.
username	Optional ACL username; NULL selects password-only AUTH.
password	Password (required).

Returns: Error value indicating success or failure.

Definition at line 802 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command_argv(), and make_error().

◆ cwist_redis_close()

void cwist_redis_close ( cwist_redis_t * r )

Close a Redis connection.

Close a connection and free the handle. Shuts the socket down first to wake a subscriber blocked in recv; this is the documented way to stop cwist_redis_subscribe(). Safe to call with NULL.

Definition at line 693 of file cwist_redis.c.

References cap, and cwist_free().

Referenced by cwist_redis_pool_create(), and cwist_redis_pool_destroy().

◆ cwist_redis_command()

cwist_error_t cwist_redis_command	(	cwist_redis_t *	r,
		const char *	cmd,
		char **	out
	)

Execute a raw Redis command and return the bulk reply.

Parameters

r	Connection.
cmd	Space-separated command string (e.g. "GET foo").
out	If non-NULL and reply is a string, receives a heap copy. Caller frees with cwist_free().

Returns: 0 on success, -1 on error.

Send a raw RESP command string and return the flattened first-payload reply.

Parameters

r	Connection handle.
cmd	Full RESP-encoded command.
out	Optional out: heap-allocated reply value (caller frees); freed internally when NULL.

Returns: Error value indicating success or failure.

Definition at line 740 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), and make_error().

Referenced by cwist_redis_del(), cwist_redis_expire(), cwist_redis_get(), cwist_redis_publish(), cwist_redis_set(), and cwist_redis_setex().

◆ cwist_redis_command_argv()

cwist_error_t cwist_redis_command_argv	(	cwist_redis_t *	r,
		size_t	argc,
		const void const	argv,
		const size_t *	argv_lens,
		char **	out,
		size_t *	out_len
	)

Execute a binary-safe Redis command expressed as explicit arguments. Reply strings are allocated with cwist_alloc() and may contain NUL bytes; use out_len to obtain their exact length.

Definition at line 764 of file cwist_redis.c.

References cap, count, CWIST_ERR_INT16, cwist_free(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_auth(), cwist_redis_pool_command_argv(), and cwist_redis_select().

◆ cwist_redis_command_argv_reply()

cwist_error_t cwist_redis_command_argv_reply	(	cwist_redis_t *	r,
		size_t	argc,
		const void const	argv,
		const size_t *	argv_lens,
		cwist_redis_reply_t **	reply
	)

Execute a binary-safe command and return the full parsed reply tree.

Required for array-reply commands such as XREADGROUP/XAUTOCLAIM. On success *reply is set (free with cwist_redis_reply_free()); on a Redis '-' error the tree still describes the error but the returned error code is non-zero.

Definition at line 632 of file cwist_redis.c.

References cap, count, CWIST_ERR_INT16, cwist_redis_reply_free(), cwist_sstring_append_len(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

◆ cwist_redis_connect()

cwist_redis_t * cwist_redis_connect	(	const char *	host,
		int	port
	)

Open a TCP connection to a Redis server.

Parameters

host	Hostname or IP address.
port	TCP port.

Returns: Connection handle, or NULL on failure.

Open a TCP connection to a Redis server and allocate the client handle.

Parameters

host	Server host name or IPv4 address.
port	Server port.

Returns: New connection handle on success, NULL on connection or allocation failure.

Definition at line 672 of file cwist_redis.c.

References cap, cwist_alloc(), and cwist_strdup().

Referenced by cwist_redis_pool_create().

◆ cwist_redis_del()

cwist_error_t cwist_redis_del	(	cwist_redis_t *	r,
		const char *	key
	)

Delete a key (DEL).

Parameters

r	Connection handle.
key	Key to delete.

Returns: Error value indicating success or failure.

Definition at line 900 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_pool_del().

◆ cwist_redis_expire()

cwist_error_t cwist_redis_expire	(	cwist_redis_t *	r,
		const char *	key,
		int	seconds
	)

Set a key's time-to-live in seconds (EXPIRE).

Parameters

r	Connection handle.
key	Key to expire.
seconds	TTL in seconds; must be positive.

Returns: Error value indicating success or failure.

Definition at line 919 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

◆ cwist_redis_get()

cwist_error_t cwist_redis_get	(	cwist_redis_t *	r,
		const char *	key,
		char **	out_value
	)

Convenience commands.

Fetch the value of a key (GET).

Parameters

r	Connection handle.
key	Key to read.
out_value	Out: heap-allocated value on success, NULL when the key is missing (caller frees).

Returns: Error value indicating success or failure.

Definition at line 840 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_pool_get().

◆ cwist_redis_pool_command_argv()

cwist_error_t cwist_redis_pool_command_argv	(	cwist_redis_pool_t *	pool,
		size_t	argc,
		const void const	argv,
		const size_t *	argv_lens,
		char **	out,
		size_t *	out_len
	)

Pool wrapper of cwist_redis_command_argv(): acquires a connection, runs the argv command, and releases the connection. See cwist_redis_command_argv() for parameter details.

Definition at line 1216 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_command_argv(), and make_error().

◆ cwist_redis_pool_command_argv_reply_timeout()

cwist_error_t cwist_redis_pool_command_argv_reply_timeout	(	cwist_redis_pool_t *	pool,
		size_t	argc,
		const void const	argv,
		const size_t *	argv_lens,
		unsigned	timeout_ms,
		cwist_redis_reply_t **	reply
	)

Run one binary-safe pooled command under a single deadline.

One CLOCK_MONOTONIC budget of timeout_ms covers waiting for a free pool connection, reconnecting a discarded connection, writing the request, and reading the complete reply. The pool's legacy blocking APIs keep their unbounded behavior; pool creation still performs blocking DNS and connects.

Connection safety: an idle connection with buffered or readable bytes, a hang-up, or a previous failure is discarded before use and replaced by a new connection to the peer address resolved by cwist_redis_pool_create() (no DNS at request time). Once any request byte has been written the command is never retried; on timeout, transport error, or malformed reply the connection is closed so a late reply can never be read by a later caller. SIGPIPE is not raised. Reply parsing is strict RESP2 with limits (8 nesting levels, 65536 nodes, 8 MiB per bulk string, 16 MiB of payload, 8 KiB status/header lines).

Replacement connections start fresh: AUTH, SELECT, HELLO and other per-connection state are not replayed. Pools used with this API must not rely on such state. Legacy pooled calls may also receive a fresh connection after a timed call discards a socket. Use a dedicated default-state pool.

Reply types follow cwist_redis_reply_t. A null bulk string is '$' with str == NULL and integer == -1; a null array is '*' with elements == 0 and integer == -1. Nested '-' elements are data.

The pool must have been created by the calling process (a pool inherited across fork() is rejected without touching it) and must not be destroyed concurrently with this call.

Parameters

pool	Pool from cwist_redis_pool_create().
argc	Number of arguments (1 .. 1048576).
argv	Argument pointers; an entry may be NULL only if its length is 0.
argv_lens	Byte length of each argument (frame limited to 512 MiB).
timeout_ms	Total budget in milliseconds; must be positive.
reply	Out: reply tree on success (free with cwist_redis_reply_free()); always set to NULL on failure.

Returns: CWIST_ERR_INT16 error whose err_i16 is 0 on success or a negative errno: -EINVAL invalid argument or timeout 0; -EPERM pool inherited from another process; -ETIMEDOUT budget exhausted; -EIO connect, send, or receive failure, or peer EOF; -EPROTO malformed or over-limit reply; -EBADMSG top-level Redis error reply (the connection stays in sync and reusable); -ENOMEM allocation failure.

Deadline-bounded pooled command; see cwist_redis.h for the contract.

Definition at line 1444 of file cwist_redis.c.

References cap, cwist_free(), cwist_malloc(), and cwist_redis_reply_free().

◆ cwist_redis_pool_create()

cwist_redis_pool_t * cwist_redis_pool_create	(	const char *	host,
		int	port,
		size_t	max_conns
	)

Create a Redis connection pool.

Parameters

host	Redis host.
port	Redis port.
max_conns	Maximum connections in pool.

Returns: Pool handle, or NULL on failure.

Create a connection pool with max_conns pre-opened connections.

Parameters

host	Server host name or IPv4 address.
port	Server port.
max_conns	Number of connections to open; must be non-zero.

Returns: New pool handle on success, NULL on any connection or allocation failure (partial state is cleaned up).

Definition at line 1037 of file cwist_redis.c.

References cap, cwist_alloc(), cwist_alloc_array(), cwist_free(), cwist_redis_close(), cwist_redis_connect(), and cwist_strdup().

Referenced by cwist_app_use_redis().

◆ cwist_redis_pool_del()

cwist_error_t cwist_redis_pool_del	(	cwist_redis_pool_t *	pool,
		const char *	key
	)

Pool wrapper of cwist_redis_del(): acquires a connection, runs DEL, and releases the connection. See cwist_redis_del() for parameter details.

Definition at line 1193 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_del(), and make_error().

◆ cwist_redis_pool_destroy()

void cwist_redis_pool_destroy ( cwist_redis_pool_t * pool )

Destroy the pool and close all connections.

Destroy a pool, closing every connection it owns. Safe to call with NULL.

Definition at line 1100 of file cwist_redis.c.

References cap, cwist_free(), and cwist_redis_close().

Referenced by cwist_app_destroy(), and cwist_app_use_redis().

◆ cwist_redis_pool_get()

cwist_error_t cwist_redis_pool_get	(	cwist_redis_pool_t *	pool,
		const char *	key,
		char **	out_value
	)

Pooled convenience commands.

Pool wrapper of cwist_redis_get(): acquires a connection, runs GET, and releases the connection. See cwist_redis_get() for parameter details.

Definition at line 1162 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_get(), and make_error().

◆ cwist_redis_pool_publish()

cwist_error_t cwist_redis_pool_publish	(	cwist_redis_pool_t *	pool,
		const char *	channel,
		const char *	message
	)

Pool wrapper of cwist_redis_publish(): acquires a connection, runs PUBLISH, and releases the connection. See cwist_redis_publish() for parameter details.

Definition at line 1204 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_publish(), and make_error().

◆ cwist_redis_pool_set()

cwist_error_t cwist_redis_pool_set	(	cwist_redis_pool_t *	pool,
		const char *	key,
		const char *	value
	)

Pool wrapper of cwist_redis_set(): acquires a connection, runs SET, and releases the connection. See cwist_redis_set() for parameter details.

Definition at line 1172 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_set(), and make_error().

◆ cwist_redis_pool_setex()

cwist_error_t cwist_redis_pool_setex	(	cwist_redis_pool_t *	pool,
		const char *	key,
		const char *	value,
		int	seconds
	)

Pool wrapper of cwist_redis_setex(): acquires a connection, runs SETEX, and releases the connection. See cwist_redis_setex() for parameter details.

Definition at line 1182 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_redis_setex(), and make_error().

◆ cwist_redis_publish()

cwist_error_t cwist_redis_publish	(	cwist_redis_t *	r,
		const char *	channel,
		const char *	message
	)

Publish a message to a channel (PUBLISH).

Parameters

r	Connection handle.
channel	Channel to publish to.
message	Message payload.

Returns: Error value indicating success or failure.

Definition at line 941 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_pool_publish().

◆ cwist_redis_reply_free()

void cwist_redis_reply_free ( cwist_redis_reply_t * reply )

Release a reply tree returned by cwist_redis_command_argv_reply().

Recursively free a reply tree, including all child elements and string payloads. Safe to call with NULL.

Definition at line 572 of file cwist_redis.c.

References cap, cwist_free(), and cwist_redis_reply_free().

Referenced by cwist_redis_command_argv_reply(), cwist_redis_pool_command_argv_reply_timeout(), and cwist_redis_reply_free().

◆ cwist_redis_select()

cwist_error_t cwist_redis_select	(	cwist_redis_t *	r,
		unsigned int	database
	)

Select the logical database for subsequent commands (SELECT).

Parameters

r	Connection handle.
database	Database index.

Returns: Error value indicating success or failure.

Definition at line 823 of file cwist_redis.c.

References cap, cwist_free(), and cwist_redis_command_argv().

◆ cwist_redis_set()

cwist_error_t cwist_redis_set	(	cwist_redis_t *	r,
		const char *	key,
		const char *	value
	)

Set the value of a key (SET).

Parameters

r	Connection handle.
key	Key to write.
value	Value to store.

Returns: Error value indicating success or failure.

Definition at line 857 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_pool_set().

◆ cwist_redis_setex()

cwist_error_t cwist_redis_setex	(	cwist_redis_t *	r,
		const char *	key,
		const char *	value,
		int	seconds
	)

Set the value of a key with a time-to-live (SETEX).

Parameters

r	Connection handle.
key	Key to write.
value	Value to store.
seconds	TTL in seconds; must be positive.

Returns: Error value indicating success or failure.

Definition at line 878 of file cwist_redis.c.

References cap, CWIST_ERR_INT16, cwist_free(), cwist_redis_command(), cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Referenced by cwist_redis_pool_setex().

◆ cwist_redis_subscribe()

cwist_error_t cwist_redis_subscribe	(	cwist_redis_t *	r,
		const char **	channels,
		cwist_redis_msg_cb	cb,
		void *	ctx
	)

Subscribe to channels on a dedicated connection.

This call blocks the current thread and invokes cb for each message. Use it inside a background thread. To stop, call cwist_redis_close() from another thread (the read loop will exit on socket error).

Parameters

r	Connection. Must not be shared with other commands.
channels	NULL-terminated array of channel names.
cb	Message callback.
ctx	User context forwarded to callback.

Returns: 0 when stopped cleanly, -1 on error.

Subscribe to channels and run a blocking message loop, invoking the callback for each incoming message.

Parameters

r	Connection handle.
channels	NULL-terminated list of channel names.
cb	Callback invoked as cb(channel, message, ctx) per message.
ctx	Opaque pointer passed through to the callback.

Returns: Zero error value; the loop ends when the connection is shut down (see cwist_redis_close()).

Definition at line 966 of file cwist_redis.c.

References cap, count, CWIST_ERR_INT16, cwist_free(), CWIST_REDIS_LINE_MAX, cwist_sstring_append(), cwist_sstring_create(), cwist_sstring_destroy(), and make_error().

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cwist_redis_msg_cb

◆ cwist_redis_pool_t

◆ cwist_redis_reply_t

◆ cwist_redis_t

Function Documentation

◆ cwist_redis_auth()

◆ cwist_redis_close()

◆ cwist_redis_command()

◆ cwist_redis_command_argv()

◆ cwist_redis_command_argv_reply()

◆ cwist_redis_connect()

◆ cwist_redis_del()

◆ cwist_redis_expire()

◆ cwist_redis_get()

◆ cwist_redis_pool_command_argv()

◆ cwist_redis_pool_command_argv_reply_timeout()

◆ cwist_redis_pool_create()

◆ cwist_redis_pool_del()

◆ cwist_redis_pool_destroy()

◆ cwist_redis_pool_get()

◆ cwist_redis_pool_publish()

◆ cwist_redis_pool_set()

◆ cwist_redis_pool_setex()

◆ cwist_redis_publish()

◆ cwist_redis_reply_free()

◆ cwist_redis_select()

◆ cwist_redis_set()

◆ cwist_redis_setex()

◆ cwist_redis_subscribe()