Data Structures
struct	Redis
	Structure that represents a Redis database instance, with one or more RedisClient connections. More...

struct	RedisClient
	Structure that represents a single Redis client connection instance. More...

struct	RedisCluster

struct	RedisEntry
	A single key / value entry, or field, in the Redis database. More...

struct	RedisMap

struct	RedisServer

struct	RESP
	Structure that represents a Redis response (RESP format). More...

Macros
#define	REDIS_ERROR
	Redis returned an error.

#define	REDIS_INCOMPLETE_TRANSFER
	The transfer to/from Redis is incomplete.

#define	REDIS_INVALID_CHANNEL
	There is no such channel in the Redis instance.

#define	REDIS_MIGRATING
	The requested key is importing, and you may query with ASKED on the specified node.

#define	REDIS_MOVED
	The requested key has moved to another cluster shard.

#define	REDIS_NULL
	Redis returned NULL.

#define	REDIS_UNEXPECTED_ARRAY_SIZE
	Got a Redis response with different number of elements than expected.

#define	REDIS_UNEXPECTED_RESP
	Got a Redis response of a different type than expected.

#define	REDISX_CHANNELS
	The number of channels a Redis instance has.

#define	REDISX_CMDBUF_SIZE 8192
	(bytes) Size of many internal arrays, and the max. send chunk size. At least ~16 bytes...

#define	REDISX_DEFAULT_SENTINEL_TIMEOUT_MILLIS 100
	[ms] Default socket read/write timeout for Redis clients

#define	REDISX_DEFAULT_TIMEOUT_MILLIS 3000
	[ms] Default socket read/write timeout for Redis clients

#define	REDISX_LISTENER_REL_PRIORITY (0.5)

#define	REDISX_MAJOR_VERSION 1
	API major version.

#define	REDISX_MINOR_VERSION 0
	API minor version.

#define	REDISX_PATCHLEVEL 0
	Integer sub version of the release.

#define	REDISX_RCVBUF_SIZE 8192
	(bytes) Redis receive buffer size (at most that much is read from the socket in a single call).

#define	REDISX_RELEASE_STRING "-devel"
	Additional release information in version, e.g. "-1", or "-rc1".

#define	REDISX_SET_LISTENER_PRIORITY FALSE
	Whether to explicitly set listener thread priorities.

#define	REDISX_TCP_BUF_SIZE 0
	(bytes) Default TCP buffer size (send/recv) for Redis clients. Values <= 0 will use system default.

#define	REDISX_TCP_PORT 6379
	Default TCP/IP port on which Redis server listens to clients.

#define	REDISX_VERSION_STRING

#define	RESP3_CONTINUED
	RESP3 dictionary of attributes (metadata)

Typedefs
typedef void(*	RedisErrorHandler) (Redis redis, enum redisx_channel channel, const char op)

typedef void(*	RedisPipelineProcessor) (RESP *response)

typedef void(*	RedisPushProcessor) (RedisClient cl, RESP message, void *ptr)

typedef int(*	RedisSocketConfigurator) (int socket, enum redisx_channel channel)

typedef void(*	RedisSubscriberCall) (const char pattern, const char channel, const char *msg, long length)

Enumerations
enum	redisx_channel { REDISX_INTERACTIVE_CHANNEL , REDISX_PIPELINE_CHANNEL , REDISX_SUBSCRIPTION_CHANNEL }

enum	redisx_protocol { REDISX_RESP2 , REDISX_RESP3 }

enum	resp_type { RESP_ARRAY , RESP_INT , RESP_SIMPLE_STRING , RESP_ERROR , RESP_BULK_STRING , RESP3_NULL , RESP3_DOUBLE , RESP3_BOOLEAN , RESP3_BLOB_ERROR , RESP3_VERBATIM_STRING , RESP3_BIG_NUMBER , RESP3_MAP , RESP3_SET , RESP3_ATTRIBUTE , RESP3_PUSH }

Functions
int	redisxAbortBlockAsync (RedisClient *cl)

int	redisxAddConnectHook (Redis redis, void(setupCall)(Redis *))

int	redisxAddDisconnectHook (Redis redis, void(cleanupCall)(Redis *))

int	redisxAddSubscriber (Redis redis, const char channelStem, RedisSubscriberCall f)

RESP *	redisxArrayRequest (Redis redis, const char args, const int length, int n, int *status)

int	redisxCheckDestroyRESP (RESP *resp, enum resp_type, int expectedSize)

int	redisxCheckRESP (const RESP *resp, enum resp_type expectedType, int expectedSize)

int	redisxCheckValid (const Redis *redis)

int	redisxClearAttributesAsync (RedisClient *cl)

void	redisxClearConnectHooks (Redis *redis)

void	redisxClearDisconnectHooks (Redis *redis)

int	redisxClearSubscribers (Redis *redis)

RESP *	redisxClusterAskMigrating (Redis redis, const char args, const int lengths, int n, int *status)

int	redisxClusterAskMigratingAsync (RedisClient cl, const char args, const int lengths, int n)

int	redisxClusterConnect (RedisCluster *cluster)

void	redisxClusterDestroy (RedisCluster *cluster)

int	redisxClusterDisconnect (RedisCluster *cluster)

Redis *	redisxClusterGetRedirection (RedisCluster cluster, const RESP redirect, boolean refresh)

Redis *	redisxClusterGetShard (RedisCluster cluster, const char key)

RedisCluster *	redisxClusterInit (Redis *node)

boolean	redisxClusterIsMigrating (const RESP *reply)

boolean	redisxClusterIsRedirected (const RESP *reply)

boolean	redisxClusterMoved (const RESP *reply)

int	redisxConnect (Redis *redis, boolean usePipeline)

RESP *	redisxCopyOfRESP (const RESP *resp)

void	redisxDebugTraffic (boolean value)

void	redisxDestroy (Redis *redis)

void	redisxDestroyEntries (RedisEntry *entries, int count)

void	redisxDestroyKeys (char **keys, int count)

void	redisxDestroyRESP (RESP *resp)

void	redisxDisconnect (Redis *redis)

int	redisxEndSubscription (Redis *redis)

int	redisxError (const char *func, int errorCode)

const char *	redisxErrorDescription (int code)

RESP *	redisxExecBlockAsync (RedisClient cl, int pStatus)

RESP *	redisxGetAttributes (Redis *redis)

const RESP *	redisxGetAttributesAsync (const RedisClient *cl)

int	redisxGetAvailable (RedisClient *cl)

int	redisxGetAvailableAsync (RedisClient *cl)

RedisClient *	redisxGetClient (Redis *redis, enum redisx_channel channel)

RESP *	redisxGetHelloData (Redis *redis)

XLookupTable *	redisxGetInfo (Redis redis, const char parameter)

char **	redisxGetKeys (Redis redis, const char table, int *n)

RedisMap *	redisxGetKeywordEntry (const RESP map, const char key)

RedisClient *	redisxGetLockedConnectedClient (Redis *redis, enum redisx_channel channel)

RedisMap *	redisxGetMapEntry (const RESP map, const RESP key)

enum redisx_protocol	redisxGetProtocol (Redis *redis)

int	redisxGetScanCount (Redis *redis)

char *	redisxGetStringValue (Redis redis, const char table, const char key, int len)

RedisEntry *	redisxGetTable (Redis redis, const char table, int *n)

int	redisxGetTime (Redis redis, struct timespec t)

RESP *	redisxGetValue (Redis redis, const char table, const char key, int status)

boolean	redisxHasComponents (const RESP *r)

boolean	redisxHasPipeline (Redis *redis)

int	redisxIgnoreReplyAsync (RedisClient *cl)

Redis *	redisxInit (const char *server)

Redis *	redisxInitSentinel (const char serviceName, const RedisServer serverList, int nServers)

boolean	redisxIsArrayType (const RESP *r)

boolean	redisxIsConnected (Redis *redis)

boolean	redisxIsEqualRESP (const RESP a, const RESP b)

int	redisxIsGlobPattern (const char *str)

boolean	redisxIsMapType (const RESP *r)

boolean	redisxIsScalarType (const RESP *r)

boolean	redisxIsStringType (const RESP *r)

boolean	redisxIsVerbose ()

int	redisxLoadScript (Redis redis, const char script, char **sha1)

int	redisxLockClient (RedisClient *cl)

int	redisxLockConnected (RedisClient *cl)

int	redisxMultiSet (Redis redis, const char table, const RedisEntry *entries, int n, boolean confirm)

int	redisxMultiSetAsync (RedisClient cl, const char table, const RedisEntry *entries, int n, boolean confirm)

int	redisxNotify (Redis redis, const char channel, const char *message)

int	redisxPing (Redis redis, const char message)

void	redisxPrintDelimited (const RESP resp, const char delim, const char *groupPrefix)

int	redisxPrintJSON (const char name, const RESP resp)

int	redisxPrintRESP (const RESP *resp)

int	redisxPublish (Redis redis, const char channel, const char *message, int length)

int	redisxPublishAsync (Redis redis, const char channel, const char *data, int length)

RESP *	redisxReadReplyAsync (RedisClient cl, int pStatus)

int	redisxReconnect (Redis *redis, boolean usePipeline)

int	redisxRemoveConnectHook (Redis redis, void(setupCall)(Redis *))

int	redisxRemoveDisconnectHook (Redis redis, void(cleanupCall)(Redis *))

int	redisxRemoveSubscribers (Redis *redis, RedisSubscriberCall f)

RESP *	redisxRequest (Redis redis, const char command, const char arg1, const char arg2, const char arg3, int status)

char *	redisxRESP2JSON (const char name, const RESP resp)

XField *	redisxRESP2XField (const char name, const RESP resp)

RESP *	redisxRunScript (Redis redis, const char sha1, const char keys, const char params, int *status)

char **	redisxScanKeys (Redis redis, const char pattern, int *n)

RedisEntry *	redisxScanTable (Redis redis, const char table, const char pattern, int n)

int	redisxSelectDB (Redis *redis, int idx)

int	redisxSendArrayRequestAsync (RedisClient cl, const char args, const int length, int n)

int	redisxSendRequestAsync (RedisClient cl, const char command, const char arg1, const char arg2, const char *arg3)

int	redisxSetDHCipherParams (Redis redis, const char dh_params_file)

int	redisxSetHostname (Redis redis, const char host)

int	redisxSetMutualTLS (Redis redis, const char cert_file, const char *key_file)

int	redisxSetPassword (Redis redis, const char passwd)

int	redisxSetPipelineConsumer (Redis *redis, RedisPipelineProcessor f)

int	redisxSetPort (Redis *redis, int port)

int	redisxSetProtocol (Redis *redis, enum redisx_protocol protocol)

int	redisxSetPushProcessor (Redis redis, RedisPushProcessor func, void arg)

int	redisxSetReplyTimeout (Redis *redis, int timeoutMillis)

int	redisxSetScanCount (Redis *redis, int count)

int	redisxSetSentinelTimeout (Redis *redis, int millis)

int	redisxSetSocketConfigurator (Redis *redis, RedisSocketConfigurator func)

int	redisxSetSocketErrorHandler (Redis *redis, RedisErrorHandler f)

int	redisxSetSocketTimeout (Redis *redis, int millis)

int	redisxSetTcpBuf (Redis *redis, int size)

int	redisxSetTLS (Redis redis, const char ca_path, const char *ca_file)

int	redisxSetTLSCiphers (Redis redis, const char cipher_list)

int	redisxSetTLSCipherSuites (Redis redis, const char list)

int	redisxSetTLSServerName (Redis redis, const char host)

int	redisxSetTLSVerify (Redis *redis, boolean value)

int	redisxSetUser (Redis redis, const char username)

int	redisxSetValue (Redis redis, const char table, const char key, const char value, boolean confirm)

int	redisxSetValueAsync (RedisClient cl, const char table, const char key, const char value, boolean confirm)

void	redisxSetVerbose (boolean value)

int	redisxSkipReplyAsync (RedisClient *cl)

int	redisxSplitText (RESP resp, char *text)

int	redisxStartBlockAsync (RedisClient *cl)

int	redisxSubscribe (Redis redis, const char channel)

int	redisxUnlockClient (RedisClient *cl)

int	redisxUnsubscribe (Redis redis, const char channel)

int	redisxValidateSentinel (const char serviceName, const RedisServer serverList, int nServers)

Detailed Description

Date: May 4, 2018

Author: Attila Kovacs

Version: 1.0

RedisX is a completely free Redis / Valkey client library, available on Github as:

https://github.com/Smithsonian/redisx

Macro Definition Documentation

◆ REDISX_LISTENER_REL_PRIORITY

#define REDISX_LISTENER_REL_PRIORITY (0.5)

[0.0:1.0] Listener priority as fraction of available range You may want to set it quite high to ensure that the receive buffer is promptly cleared.

◆ REDISX_VERSION_STRING

#define REDISX_VERSION_STRING

The version string for this library

Typedef Documentation

◆ RedisErrorHandler

typedef void(* RedisErrorHandler) (Redis *redis, enum redisx_channel channel, const char *op)

User-specified callback function for handling RedisX errors from socket-level read / write calls. It's mainly there for the application to perform any cleanup as necessary or to report the error. However, it can also interacti with the Redis instance in limited ways. The implementation should follow a set of basic rules:

It should not call synchronized functions on the affected client, including attempts to connect, disconnect, or reconnect the client.
It may call Async functions for the client (the client is in a locked state when the handler is called).
It should not attempt to lock or unlock the affected client.
It may use errno to gather information about the source of the error, and may even change or reset errno, to change behavior (e.g. re-setting to EAGAIN or EWOULBLOCK will keep the client connected and the return status of the failed call will become X_TIMEDOUT; or setting it to any other value will disconnect the client and the failed call will return X_NO_SERVICE instead.).
The limitations can by bypassed by placing the error on a queue and let an asynchronous thread take it from there.

Parameters

redis	Pointer to the RedisX instance
channel	the channel over which the error occurred
op	the name/ID of the operation where the error occurred.

◆ RedisPipelineProcessor

typedef void(* RedisPipelineProcessor) (RESP *response)

A user-defined function for consuming responses from a Redis pipeline connection. The implementation should follow a set of simple rules:

the implementation should not destroy the RESP data. The RESP will be destroyed automatically after the call returns. However, the call may retain any data from the RESP itself, provided the data is de-referenced from the RESP before return.
The implementation should not block (aside from maybe a quick mutex unlock) and return quickly, so as to not block the client for long periods
If extensive processing or blocking calls are required to process the message, it is best to simply place a copy of the RESP on a queue and then return quickly, and then process the message asynchronously in a background thread.

Parameters

response A response received from the pipeline client.

See also: redisxSetPipelineConsumer()

◆ RedisPushProcessor

typedef void(* RedisPushProcessor) (RedisClient *cl, RESP *message, void *ptr)

A user-defined function for consuming push messages from a Redis client. The implementation should follow a set of simple rules:

the implementation should not destroy the RESP data. The RESP will be destroyed automatically after the call returns. However, the call may retain any data from the RESP itself, provided that such data is de-referenced from the RESP before the return.
The implementation should not block (aside from maybe a quick mutex unlock) and return quickly, so as to not block the client for long periods
If extensive processing or blocking calls are required to process the message, it is best to simply place a copy of the RESP on a queue and then return quickly, and then process the message asynchronously in a background thread.
The client on which the push notification originated will be locked when this function is called, waiting for a response to an earlier query. Thus the implementation should not attempt to lock the client again or release the lock. It may send asynchronous requests on the client, e.g. via redisxSendRequestAsync(), but it should not try to read a response (given that the client is blocked for another read operation). If more flexible client access is needed, the implementation should make a copy of the RESP and place it on a queue for asynchronous processing by another thread.

Parameters

cl	The Redis client that sent the push. The client is locked for exlusive access when this function is called.
message	The RESP3 message that was pushed by the client
ptr	Additional data passed along.

See also: redisxSetPushProcessor()

◆ RedisSocketConfigurator

typedef int(* RedisSocketConfigurator) (int socket, enum redisx_channel channel)

User callback function allowing additional customization of the client socket before connection.

Parameters

socket	The socket descriptor.
channel	REDISX_INTERACTIVE_CHANNEL, REDISX_PIPELINE_CHANNEL, REDISX_SUBSCRIPTION_CHANNEL

Returns: X_SUCCESS (0) if the socket may be used as is after the return. Any other value will indicate that the socket should not be used and that the caller itself should fail with an error.

◆ RedisSubscriberCall

typedef void(* RedisSubscriberCall) (const char *pattern, const char *channel, const char *msg, long length)

A type of function that handles Redis PUB/SUB messages. These functions should follow a set of basic rules:

The call should return promptly and never block for significant periors. If it has blocking calls or if extended processing is required, the function should simply place a copy of the necessary information on a queue and process queued entries in a separate thread. (The call arguments will not persist beyond the scope of the call, so don't attempt to place them directly in a queue.)
The subscriber call should not attempt to modify or free() the strings it is called with. The same strings maybe used by other subscribers, and thus modifying their content would produce unpredictable results with those subscribers.
If the call needs to manipulate the supplied string arguments, it should operate on copies (e.g. obtained via xStringCopy()).
The caller should free up any temporary resources it allocates, including copies of the argument strings, before returning. However, it should never call free() on the supplied arguments directly.

Parameters

pattern	The subscription pattern for which this notification came for or NULL if not a pattern match.
channel	The PUB/SUB channel on which the message arrived.
msg	A pointer to the message content received. The message buffer itself is not expected to last beyond the call, so the function f() should make a copy if it for any persistent use.
length	The number of bytes in the message. Since Redis messages can be binary a '\0' termination should no be assumed. Instead, the length of the message is specified explicitly.

Enumeration Type Documentation

◆ redisx_channel

enum redisx_channel

RedisX channel IDs. RedisX uses up to three separate connections to the server: (1) an interactive client, in which each query is a full round trip, (2) a pipeline clinet, in which queries are submitted in bulk, and responses arrive asynchronously, and (3) a substription client devoted to PUB/SUB requests and push messages. Not all clients are typically initialized at start. The interactive channel is always connected; the pipeline client can be selected when connecting to the server; and the subscription client is connected as needed to process PUB/SUB requests.

Enumerator
REDISX_INTERACTIVE_CHANNEL	Redis channel number for interactive queries.
REDISX_PIPELINE_CHANNEL	Redis channel number for pipelined transfers.
REDISX_SUBSCRIPTION_CHANNEL	Redis channel number for PUB/SUB messages.

◆ redisx_protocol

enum redisx_protocol

The RESP protocol to use for a Redis instance. Redis originally used RESP2, but later releases added support for RESP3.

Enumerator
REDISX_RESP2	RESP2 protocol.
REDISX_RESP3	RESP3 protocol (since Redis version 6.0.0)

◆ resp_type

enum resp_type

Enumeration of RESP component types. These are the first character IDs for the standard RESP interface implemented by Redis.

Enumerator
RESP_ARRAY	RESP array type.
RESP_INT	RESP integer type.
RESP_SIMPLE_STRING	RESP simple string type.
RESP_ERROR	RESP error message type.
RESP_BULK_STRING	RESP bulk string type.
RESP3_NULL	RESP3 null value.
RESP3_DOUBLE	RESP3 floating-point value.
RESP3_BOOLEAN	RESP3 boolean value.
RESP3_BLOB_ERROR	RESP3 blob error.
RESP3_VERBATIM_STRING	RESP3 verbatim string (with type)
RESP3_BIG_NUMBER	RESP3 big integer / decimal.
RESP3_MAP	RESP3 dictionary of key / value.
RESP3_SET	RESP3 unordered set of elements.
RESP3_ATTRIBUTE	RESP3 dictionary of attributes (metadata)
RESP3_PUSH	RESP3 dictionary of attributes (metadata)

Function Documentation

◆ redisxAbortBlockAsync()

int redisxAbortBlockAsync ( RedisClient * cl )

Abort an atomic transaction block. It sends DISCARD. This function should be called with an exclusive lock on a connected client, and after starting an execution block with redisxStartBlockAsync().

Parameters

cl	Pointer to a Redis client

Returns: X_SUCCESS (0) if successful, or X_NULL if the client is NULL, or X_NO_SERVICE if not connected ot the client or if send() failed, or X_NO_INIT if the client was not initialized.

See also: redisxStartBlockAsync()

References redisxIgnoreReplyAsync(), TRUE, and X_SUCCESS.

◆ redisxAddConnectHook()

int redisxAddConnectHook	(	Redis *	redis,
		void()(Redis )	setupCall
	)

Adds a connect call hook, provided it is not already part of the setup routine.

Parameters

redis	Pointer to a Redis instance.
setupCall	User-specified callback routine to be called after the Redis instance has been connected. It will be passed a pointer to the Redis instance, which triggered the call by having established connection.

Returns: X_SUCCESS (0) if successful or else X_NULL if either of the arguments is NULL.

References x_error(), X_NULL, X_SUCCESS, and xvprintf.

◆ redisxAddDisconnectHook()

int redisxAddDisconnectHook	(	Redis *	redis,
		void()(Redis )	cleanupCall
	)

Adds a cleanup call, provided it is not already part of the cleanup routine, for when the specified Redis instance is disconnected.

Parameters

redis	Pointer to a Redis instance.
cleanupCall	User specified function to call when Redis is disconnected. It will be passed a pointer to the Redis instance, which triggered the call by having disconnected from the Redis server.

Returns: X_SUCCESS (0) if successful or else X_NULL if either of the arguments is NULL.

References x_error(), X_NULL, X_SUCCESS, and xvprintf.

◆ redisxAddSubscriber()

int redisxAddSubscriber	(	Redis *	redis,
		const char *	channelStem,
		RedisSubscriberCall	f
	)

Add a targeted subscriber processing function to the list of functions that process Redis PUB/SUB responses. You will still have to subscribe the relevant PUB/SUB messages from redis separately, using redisxSubscribe() before any messages are delivered to this client. If the subscriber with the same callback function and channel stem is already added, this call simply return and will NOT create a duplicate enry. However, the same callback may be added multiple times with different channel stems (which pre-filter what messages each of the callbacks may get).

Parameters

redis	Pointer to a Redis instance.
channelStem	If NULL, the consumer will receive all Redis messages published to the given channel. Otherwise, the consumer will be notified only if the incoming channel begins with the specified stem.
f	A function that consumes subscription messages.

See also: redisxRemoveSubscribers(); redisxSubscribe()

References X_SUCCESS, x_warn(), xStringCopyOf(), and xvprintf.

◆ redisxArrayRequest()

RESP * redisxArrayRequest	(	Redis *	redis,
		const char **	args,
		const int *	lengths,
		int	n,
		int *	status
	)

Returns the result of the most generic type of Redis request with any number of arguments. This is not the highest throughput mode (that would be sending asynchronous pipeline request, and then asynchronously collecting the results such as with redisxSendArrayRequestAsync() / redisxReadReplyAsync(), because it requires separate network roundtrips for each and every request. But, it is simple and perfectly good method when one needs to retrieve only a few (<1000) variables per second...

This is the base interactive query, which is used by all sorts of other interactive transactions. It handles MOVED and ASK redirections for Redis clusters automatically and transparently, so long as the target node is a known member of the cluster from before or immediately after the migration message was received.

Parameters

redis	Pointer to a Redis instance.
args	An array of strings to send to Redis, corresponding to a single query. If you have an `char ` array, you may need to cast to `(const char )` to avoid compiler warnings.
lengths	Array indicating the number of bytes to send from each string argument. Zero values can be used to determine the string length automatically using strlen(), and the length argument itself may be NULL to determine the lengths of all string arguments automatically.
n	Number of string arguments.
status	Pointer to the return error status. If not NULL, it will be populated with one of: X_SUCCESS on success. X_NO_INIT if the Redis client library was not initialized via redisxInit(). X_NULL if the argument is NULL or n<1. X_TIMEDOUT if the reading of the response timed out. X_NO_SERVICE if not connected to Redis. X_FAILURE If there was a socket level error.

Returns: A freshly allocated RESP array containing the Redis response, or NULL if no valid response could be obtained.

See also: redisxRequest(); redisxSendArrayRequestAsync(); redisxReadReplyAsync()

References Redis::interactive, redisxArrayRequest(), redisxCheckValid(), redisxClearAttributesAsync(), redisxClusterAskMigrating(), redisxClusterGetRedirection(), redisxClusterIsMigrating(), redisxClusterIsRedirected(), redisxLockConnected(), redisxReadReplyAsync(), redisxSendArrayRequestAsync(), redisxUnlockClient(), x_error(), X_NULL, X_SUCCESS, and x_trace_null().

◆ redisxCheckDestroyRESP()

int redisxCheckDestroyRESP	(	RESP *	resp,
		enum resp_type	expectedType,
		int	expectedSize
	)

Like redisxCheckRESP(), but it also destroys the RESP in case of an error.

Parameters

resp	Pointer to the RESP structure from Redis.
expectedType	The RESP type expected (e.g. RESP_ARRAY) or 0 if not checking type.
expectedSize	The expected size of the RESP (array or bytes) or <=0 to skip checking

Returns: The return value of redisxCheckRESP().

See also: redisxCheckRESP()

References redisxCheckRESP(), and redisxDestroyRESP().

◆ redisxCheckRESP()

int redisxCheckRESP	(	const RESP *	resp,
		enum resp_type	expectedType,
		int	expectedSize
	)

Checks a Redis RESP for NULL values or unexpected values.

Parameters

resp	Pointer to the RESP structure from Redis.
expectedType	The RESP type expected (e.g. RESP_ARRAY) or 0 if not checking type.
expectedSize	The expected size of the RESP (array or bytes) or <=0 to skip checking

Returns: X_SUCCESS (0) if the RESP passes the tests, or X_NULL if the RESP is NULL (garbled response). REDIS_NULL if Redis returned (nil), REDIS_UNEXPECTED_TYPE if got a reply of a different type than expected REDIS_UNEXPECTED_ARRAY_SIZE if got a reply of different size than expected.

or the error returned in resp->n.

References RESP::n, REDIS_MIGRATING, REDIS_MOVED, REDIS_NULL, REDIS_UNEXPECTED_RESP, redisxClusterIsMigrating(), redisxClusterMoved(), RESP3_BOOLEAN, RESP3_NULL, RESP_INT, RESP::type, RESP::value, x_error(), X_FAILURE, X_NULL, and X_SUCCESS.

◆ redisxCheckValid()

int redisxCheckValid ( const Redis * redis )

Checks that a redis instance is valid.

Parameters

redis The Redis instance

Returns: X_SUCCESS (0) if the instance is valid, or X_NULL if the argument is NULL (errno = EINVAL), or else X_NO_INIT (errno = ENXIO) if the redis instance is not initialized.

References x_error(), X_NO_INIT, X_NULL, and X_SUCCESS.

◆ redisxClearAttributesAsync()

int redisxClearAttributesAsync ( RedisClient * cl )

Clears the attributes for the specified client. The caller should have an exclusive lock on the client's mutex prior to making this call.

Typically a user migh call this function prior to calling redisxReadReplyAsync() on the same client, to ensure that any attributes that are available after the read will be the ones that were sent with the last response from the server.

Parameters

cl	The Redis client instance

Returns: X_SUCCESS (0) if successful, or else X_NULL if the client is NULL.

See also: redisxGetAttributesAsync(); redisxReadReplyAsync(); redisxGetLockedConnected()

References X_SUCCESS.

◆ redisxClearConnectHooks()

void redisxClearConnectHooks ( Redis * redis )

Removes all connect hooks, that is no user callbacks will be made when the specified Redis instance is connected.

Parameters

redis Pointer to a Redis instance.

References X_SUCCESS, and xvprintf.

◆ redisxClearDisconnectHooks()

void redisxClearDisconnectHooks ( Redis * redis )

Removes all disconnect hooks, that is no user-specified callbacks will be made when the specified Redis instance is disconnected.

Parameters

redis Pointer to a Redis instance.

References X_SUCCESS, and xvprintf.

◆ redisxClearSubscribers()

int redisxClearSubscribers ( Redis * redis )

Stops the custom consumption of PUB/SUB messages from Redis.

Parameters

redis Pointer to a Redis instance.

Returns: X_SUCCESS (0) if successful, or X_NULL if the redis instance is NULL.

References xvprintf.

◆ redisxClusterAskMigrating()

RESP * redisxClusterAskMigrating	(	Redis *	redis,
		const char **	args,
		const int *	lengths,
		int	n,
		int *	status
	)

Makes a redirected transaction using the ASKING directive to the specific client. This should be in response to an -ASK redirection error to obtain a key that is in a slot that is currently migrating. The requested Redis command arguments are sent prefixed with the 'ASKING' directive, as per the Redis Cluster specification.

Parameters

redis	Redirected Redis instance, e.g. from redisxClusterGetRedirect()
args	Original command arguments that were redirected
lengths	Original argument byte lengths redirected (or NULL to use strlen() automatically).
n	Original number of arguments.
status	Pointer to integer in which to return status: X_SUCCESS (0) if successful or else and error code <0.

Returns: The response to the ASKING query from the redirected server.

See also: redisxClusterAskMigratingAsync(); redisxClusterIsMigrating(); redisxClusterGetRedirect(); redisxArrayRequest()

References Redis::interactive, redisxCheckValid(), redisxClearAttributesAsync(), redisxClusterAskMigratingAsync(), redisxLockConnected(), redisxReadReplyAsync(), redisxUnlockClient(), X_SUCCESS, and x_trace_null().

◆ redisxClusterAskMigratingAsync()

int redisxClusterAskMigratingAsync	(	RedisClient *	cl,
		const char **	args,
		const int *	lengths,
		int	n
	)

Makes a redirected request using the ASKING directive to the specific client. This should be in response to an -ASK redirection error to obtain a key that is in a slot that is currently migrating. The requested Redis command arguments are sent prefixed with the 'ASKING' directive, as per the Redis Cluster specification.

This function should be called with exclusive access to the client.

Parameters

cl	Locked client on a redirected Redis instance, e.g. from redisxClusterGetRedirect()
args	Original command arguments that were redirected
lengths	Original argument byte lengths redirected (or NULL to use strlen() automatically).
n	Original number of arguments.

Returns: X_SUCCESS (0) if successful or else and error code <0.

See also: redisxClusterAskMigrating(); redisxClusterIsMigrating(); redisxClusterGetRedirect(); redisxArrayRequest()

References redisxSendArrayRequestAsync(), x_error(), X_FAILURE, X_NO_SERVICE, X_NULL, X_SUCCESS, and xStringCopyOf().

◆ redisxClusterConnect()

int redisxClusterConnect ( RedisCluster * cluster )

Connects all shards of a Redis cluster. Shards normally get connected on demand. Thus, this function is only necessary if the user wants to ensure that all shards are connected before using the cluster.

Note, that if the cluster configuration changes while connected, the automatically reconfigured cluster will not automatically reconnect to the new shards during the reconfiguration. However, the new shards will still connect on demand when accessed via redisClusterGetShard().

Parameters

cluster Pointer to a Redis cluster configuration

Returns: X_SUCCESS (0) if successful, or else a RedisX error code <0 (errno will also indicate the type of error).

See also: redisxClusterInit(); redisxClusterConnect(); redisxClusterGetShard()

References RedisCluster::priv, redisxConnect(), x_error(), X_NO_INIT, X_NULL, X_SUCCESS, x_trace(), and xvprintf.

◆ redisxClusterDestroy()

void redisxClusterDestroy ( RedisCluster * cluster )

Destroys a Redis cluster configuration, freeing up all resources used, but not before disconnecting from all shards that may be in a connected state.

Parameters

cluster Pointer to a Redis cluster configuration.

See also: redisxClusterInit()

References RedisCluster::priv, and redisxClusterDisconnect().

◆ redisxClusterDisconnect()

int redisxClusterDisconnect ( RedisCluster * cluster )

Disconnects from all shards of a Redis cluster. Note, that a cluster can still be used even after it is disconnected, since each call to redisxClusterGetShard() will automatically reconnect the requested shard as needed.

Parameters

cluster Pointer to a Redis cluster configuration

Returns: X_SUCCESS (0) if successful, or else a RedisX error code <0 (errno will also indicate the type of error).

See also: redisxClusterInit(); redisxClusterConnect()

References RedisCluster::priv, redisxDisconnect(), x_error(), X_NO_INIT, X_NULL, X_SUCCESS, and xvprintf.

◆ redisxClusterGetRedirection()

Redis * redisxClusterGetRedirection	(	RedisCluster *	cluster,
		const RESP *	redirect,
		boolean	refresh
	)

Parses a -MOVED or -ASK redirection response from a Redis cluster node, to obtain the shard from which the same keyword that caused the error can now be accessed.

Parameters

cluster	Redis cluster configuration
redirect	the redirection response sent to a keyword query
refresh	whether it should refresh the cluster configuration and try again if the redirection target is not found in the current cluster configuration.

Returns: the migrated server, from which the keyword should be queried now, or NULL if either pointer argument is NULL or if the RESP is not a redirection response (errno will be set to EINVAL), or if the redirected address is not part of a the cluster configuration (errno set to ENXIO if the cluster is not initialized, or else to EAGAIN).

See also: redisxClusterMoved(); redisxClusterIsMigrating(); redisxClusterAskMigrating()

References redisxClusterIsMigrating(), redisxClusterMoved(), RESP::value, x_error(), X_PARSE_ERROR, and xStringCopyOf().

◆ redisxClusterGetShard()

Redis * redisxClusterGetShard	(	RedisCluster *	cluster,
		const char *	key
	)

Returns the Redis server in a cluster which is to be used for queries relating to the specified Redis keyword. In Redis cluster configurations, the database is distributed in a way that each cluster node serves only a subset of the Redis keys. Thus, this function allows to identify the node that serves a given key. The function supports Redish hashtags according to the specification.

Parameters

cluster	Pointer to a Redis cluster configuration
key	The Redis keyword of interest. It may use hashtags (i.e., if the keyword contains a segment enclosed in {} brackets, then the hash will be calculated on the bracketed segment only. E.g. `{user:1000}.name` and `{user:1000}.address` will both return the same hash for `user:1000` only. NULL and empty keys are allowed and will return the shard for slot 0.

Returns: A connected Redis server (cluster shard), which can be used for queries on the given keyword, or NULL if either input pointer is NULL (errno = EINVAL), or the cluster has not been initialized (errno = ENXIO), or if no node could be connected to serve queries for the given key (errno = EAGAIN).

See also: redisxClusterInit(); redisxClusterMoved()

References RedisCluster::priv, rConnectAsync(), redisxIsConnected(), x_error(), X_NO_INIT, X_NULL, and X_SUCCESS.

◆ redisxClusterInit()

RedisCluster * redisxClusterInit ( Redis * node )

Initializes a Redis cluster configuration using a known cluster node. The call will connect to the specified node (if not already connected), and will query the cluster configuration from it. On return the input node's connection state remains what it was prior to the call.

The caller may try multiple nodes from a list of known cluster nodes, until a valid (non-NULL) configuration is returned.

The returned cluster will inherit configuration from the node, including user authentication, socket configuration, connection / disconnection hooks, and asynchronous processing functions. Thus, you may configure the node as usual prior to this call, knowing that the nodes in the cluster will be configured the same way also.

Parameters

node	A known cluster node (connected or not). It's configuration will be used for all cluster nodes discovered also.

Returns: The Redis cluster configuration obtained from the node, or else NULL if there was an error (errno may indicate the type of error).

See also: redisxClusterGetShard(); redisxClusterDestroy(); redisxClusterConnect()

References RedisCluster::priv, redisxClusterDestroy(), redisxHasPipeline(), and x_trace_null().

◆ redisxClusterIsMigrating()

boolean redisxClusterIsMigrating ( const RESP * reply )

Checks if the reply is an error indicating that the query is for a slot that is currently migrating to another shard (i.e., ASK redirection). You may need to use an ASKING directive, e.g. via redisxClusterAskMigrating() on the node specified in the message to access the key.

Parameters

reply The response obtained from the Redis shard / server.

Returns: TRUE (1) if the reply is an error indicating that the cluster has been reconfigured and the key has moved to another shard, or else FALSE (0).

See also: redisxClusterMoved(); redisxClusterIsRedirected(); redisxClusterAskMigrating()

References FALSE, RESP::n, RESP_ERROR, RESP::type, and RESP::value.

◆ redisxClusterIsRedirected()

boolean redisxClusterIsRedirected ( const RESP * reply )

Checks if the reply is an error indicating that the query should be redirected to another node (i.e., MOVED or ASK redirection).

Parameters

reply The response obtained from the Redis shard / server.

Returns: TRUE (1) if the reply is an error indicating that the query should be directed to another node, or else FALSE (0).

See also: redisxClusterMoved(); redisxClusterIsMigrating()

References redisxClusterIsMigrating(), and redisxClusterMoved().

◆ redisxClusterMoved()

boolean redisxClusterMoved ( const RESP * reply )

Checks if the reply is an error indicating that the cluster has been reconfigured and the request can no longer be fulfilled on the given shard (i.e., MOVED redirection). You might want to obtain the new shard using redisxClusterGetShard() again, and re-submit the request to the new shard.

Parameters

reply The response obtained from the Redis shard / server.

Returns: TRUE (1) if the reply is an error indicating that the cluster has been reconfigured and the key has moved to another shard, or else FALSE (0).

See also: redisxClusterIsMigrating(); redisxClusterIsRedirected(); redisxClusterGetShard()

References FALSE, RESP::n, RESP_ERROR, RESP::type, and RESP::value.

◆ redisxConnect()

int redisxConnect	(	Redis *	redis,
		boolean	usePipeline
	)

Connects to a Redis server.

Parameters

redis	Pointer to a Redis instance.
usePipeline	TRUE (non-zero) if Redis should be connected with a pipeline client also, or FALSE (0) if only the interactive client is needed.

Returns: X_SUCCESS (0) if successfully connected to the Redis server. X_NO_INIT if library was not initialized via initRedis(). X_ALREADY_OPEN if already connected. X_NO_SERVICE if the connection failed. X_NULL if the redis argument is NULL.

See also: redisxInit(); redisxSetPort(); redisxSetUser(); redisxSetPassword(); redisxSetTcpBuf(); redisxSelectDB(); redisxDisconnect()

References rConnectAsync(), and X_SUCCESS.

◆ redisxCopyOfRESP()

RESP * redisxCopyOfRESP ( const RESP * resp )

Creates an independent deep copy of the RESP, which shares no references with the original.

Parameters

resp	The original RESP data structure (it may be NULL).

Returns: A copy of the original, with no shared references.

References RedisMap::key, RESP::n, redisxCopyOfRESP(), RESP3_ATTRIBUTE, RESP3_BIG_NUMBER, RESP3_BLOB_ERROR, RESP3_DOUBLE, RESP3_MAP, RESP3_PUSH, RESP3_SET, RESP3_VERBATIM_STRING, RESP_ARRAY, RESP_BULK_STRING, RESP_ERROR, RESP_SIMPLE_STRING, RESP::type, RESP::value, and RedisMap::value.

◆ redisxDebugTraffic()

void redisxDebugTraffic ( boolean value )

Enable or disable verbose reporting of all Redis bound traffic. It may be useful when debugging programs that use the redisx interface. Verbose reporting is DISABLED by default.

Parameters

value TRUE to enable verbose reporting, or FALSE to disable.

See also: redisxSetVerbose()

References FALSE, and TRUE.

◆ redisxDestroy()

void redisxDestroy ( Redis * redis )

Destroys a Redis intance, disconnecting any clients that may be connected, and freeing all resources used by that Redis instance.

Parameters

redis Pointer to a Redis instance.

References Redis::id, REDISX_CHANNELS, redisxClearSubscribers(), redisxDestroyRESP(), redisxDisconnect(), and redisxIsConnected().

◆ redisxDestroyEntries()

void redisxDestroyEntries	(	RedisEntry *	entries,
		int	count
	)

Destroy a RedisEntry array with dynamically allocate keys/values, such as returned e.g. by redisxScanTable().

IMPORTANT:

You should not use this function to destroy RedisEntry[] arrays, which contain static string references (keys or values). If the table contains only static references you can simply call free() on the table. Otherwise, you will have to first free only the dynamically sized string fields within before calling free() on the table itself.

Parameters

entries	Pointer to the entries array (or single entry data). It may be NULL, in which case this call will return immediately.
count	The number of elements contained in the array

See also: redisxScanTable(); redisxGetTable()

References RedisEntry::key, and RedisEntry::value.

◆ redisxDestroyKeys()

void redisxDestroyKeys	(	char **	keys,
		int	count
	)

Destroy an array of keywords (i.e. an array of string pointers), such as returned e.g. by redisxScanKeys().

Parameters

keys	An array of string pointers
count	The number of strings contained in the array. It may be NULL., in which case this call will return immediately.

See also: redisxScanKeys(); redisxGetKeys()

◆ redisxDestroyRESP()

void redisxDestroyRESP ( RESP * resp )

Frees up the resources used by a RESP structure that was dynamically allocated. The call will segfault if the same RESP is destroyed twice or if the argument is a static allocation.

Parameters

resp	Pointer to the RESP structure to be destroyed, which may be NULL (no action taken).

References RedisMap::key, RESP::n, redisxDestroyRESP(), RESP3_ATTRIBUTE, RESP3_MAP, RESP3_PUSH, RESP3_SET, RESP_ARRAY, RESP::type, RESP::value, and RedisMap::value.

◆ redisxDisconnect()

void redisxDisconnect ( Redis * redis )

Disconnect all clients from the Redis server.

Parameters

redis Pointer to a Redis instance.

References rDisconnectAsync(), redisxCheckValid(), and X_SUCCESS.

◆ redisxEndSubscription()

int redisxEndSubscription ( Redis * redis )

Unsubscribes from all channels, stops the subscription listener thread, and closes the subscription client connection.

Parameters

redis Pointer to a Redis instance.

Returns: X_SUCCESS (0) if successful or else an error code (<0).

See also: redisxUnsubscribe()

References X_SUCCESS.

◆ redisxError()

int redisxError	(	const char *	func,
		int	errorCode
	)

Prints a descriptive error message to stderr, and returns the error code.

Parameters

func	A string that describes the function or location where the error occurred.
errorCode	The error code that describes the failure.

Returns: the error code.

References MAX_DEBUG_ERROR_COUNT, REDIS_INCOMPLETE_TRANSFER, redisxErrorDescription(), and xDebug.

◆ redisxErrorDescription()

const char * redisxErrorDescription ( int code )

Returns a string description for one of the RM error codes.

Parameters

code	One of the error codes defined in 'rm.h' or in 'redisrm.h' (e.g. X_NO_PIPELINE)

Returns: A constant string with the error description.

References REDIS_ERROR, REDIS_INCOMPLETE_TRANSFER, REDIS_INVALID_CHANNEL, REDIS_NULL, REDIS_UNEXPECTED_ARRAY_SIZE, REDIS_UNEXPECTED_RESP, and xErrorDescription().

◆ redisxExecBlockAsync()

RESP * redisxExecBlockAsync	(	RedisClient *	cl,
		int *	pStatus
	)

Finish and execute an atomic transaction block. It sends EXEC, skips through all OK and QUEUED acknowledgements, and returns the reply to the transaction block itself. This function should be called with an exclusive lock on a connected client.

Parameters

cl	Pointer to a Redis client
pStatus	Pointer to int in which to return error status. or NULL if not required.

Returns: The array RESP returned by EXEC, or NULL if there was an error.

See also: redisxStartBlockAsync(); redisxAbortBlockAsync(); redisxGetLockedConnected()

References redisxDestroyRESP(), redisxReadReplyAsync(), redisxSkipReplyAsync(), RESP_ARRAY, RESP_ERROR, TRUE, RESP::type, x_error(), X_SUCCESS, and x_trace_null().

◆ redisxGetAttributes()

RESP * redisxGetAttributes ( Redis * redis )

Returns a copy of the attributes sent along with the last interative request. The user should destroy the returned RESP after using it by calling redisxDestroyRESP().

Parameters

redis Pointer to a Redis instance.

Returns: The attributes (if any) that were sent along with the last response on the interactive client.

See also: redisxGetAttributeAsync(); redisxRequest(); redisxArrayRequest(); redisxDestroyRESP()

References Redis::interactive, redisxCheckValid(), redisxCopyOfRESP(), redisxGetAttributesAsync(), redisxLockConnected(), redisxUnlockClient(), X_SUCCESS, and x_trace_null().

◆ redisxGetAttributesAsync()

const RESP * redisxGetAttributesAsync ( const RedisClient * cl )

Returns the attributes (if any) that were last sent along a response to the client. This function should be called only if the caller has an exclusive lock on the client's mutex. Also, there are a few rules the caller should follow:

The caller should not block the client for long and return quickly. If it has blocking calls, or requires extensive processing, it should make a copy of the RESP first, and release the lock immediately after.
The caller must not attempt to call free() on the returned RESP

Normally the user would typically call this function right after a redisxReadReplyAsync() call, for which atributes are expected. The caller might also want to call redisxClearAttributeAsync() before attempting to read the response to ensure that the attributes returned are for the same reply from the server.

Parameters

cl	The Redis client instance

Returns: The attributes last received (possibly NULL).

See also: redisxGetAttributes(); redisxClearAttributesAsync(); redisxReadReplyAsync(); redisxGetLockedConnected()

References x_error().

◆ redisxGetAvailable()

int redisxGetAvailable ( RedisClient * cl )

Returns the number of bytes of response available on the given Redis client connection. This is the synchronized version, which will obtain a exclusive lock on the client before determining the result.

Parameters

cl	a locked and connected Redis client

Returns: the number of bytes of response available on the client, or else an error code <0.

See also: redisxGetAvailableAsync()

References redisxGetAvailable(), redisxLockConnected(), and redisxUnlockClient().

◆ redisxGetAvailableAsync()

int redisxGetAvailableAsync ( RedisClient * cl )

Returns the number of bytes of response available on the given Redis client connection. This version assumes the caller has exclusive access to the client.

Parameters

cl	a locked and connected Redis client

Returns: the number of bytes of response available on the client, or else an error code <0.

See also: redisxGetAvailable(); redisxGetLockConnected(); redisxReadReplyAsync()

References x_error(), and X_FAILURE.

◆ redisxGetClient()

RedisClient * redisxGetClient	(	Redis *	redis,
		enum redisx_channel	channel
	)

Returns the redis client for a given connection type in a Redis instance.

Parameters

redis	Pointer to a Redis instance.
channel	REDISX_INTERACTIVE_CHANNEL, REDISX_PIPELINE_CHANNEL, or REDISX_SUBSCRIPTION_CHANNEL

Returns: Pointer to the matching Redis client, or NULL if redis is null (EINVAL) or not initialized (EAGAIN) or if the channel argument is invalid (ECHRNG).

See also: redisxGetLockedConnectedClient()

References REDISX_CHANNELS, redisxCheckValid(), x_error(), X_SUCCESS, and x_trace_null().

◆ redisxGetHelloData()

RESP * redisxGetHelloData ( Redis * redis )

Returns a copy of the RESP map that the Redis server has sent us as a response to HELLO on the last client connection, or NULL if HELLO was not used or available.

Parameters

redis The redis instance

Returns: A copy of the response sent by HELLO on the last client connection, or NULL.

See also: redisxSetProtocol(); redisxGetInfo()

References redisxCopyOfRESP(), and x_trace_null().

◆ redisxGetInfo()

XLookupTable * redisxGetInfo	(	Redis *	redis,
		const char *	parameter
	)

Returns the result of an INFO query (with the optional parameter) as a lookup table of keywords and string values.

Parameters

redis	Pointer to Redis instance
parameter	Optional parameter to pass with INFO, or NULL.

Returns: a newly created lookup table with the string key/value pairs of the response from the Redis server, or NULL if there was an error. The caller should destroy the lookup table after using it.

See also: redisxGetInfoAsync(); redisxGetHelloData()

References rConsumeInfoReply(), redisxRequest(), X_SUCCESS, and x_trace_null().

◆ redisxGetKeys()

char ** redisxGetKeys	(	Redis *	redis,
		const char *	table,
		int *	n
	)

Returns all the key names stored in a given hash table

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	table	The hashtable from which to retrieve a value or NULL if to use the global table.
[out]	n	Pointer to the integer in which the number of elements or an error (<0) is returned. It may return an error value from redisxRequest(), or:

REDIS_NULL If got a null or empty response from Redis UNEXPECTED_RESP If the response from Redis was not the expected array type

Returns: An array with pointers to key names from this table or NULL if there was an error (see parameter n for an error status from redisx.h / xchange.h).

See also: redisxScanKeys(); redisxDestroyKeys()

References RESP::n, redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_ARRAY, RESP::value, x_error(), X_NULL, and x_trace_null().

◆ redisxGetKeywordEntry()

RedisMap * redisxGetKeywordEntry	(	const RESP *	map,
		const char *	key
	)

Retrieves a entry, by its string keyword, from a map-type RESP data structure.

Parameters

map	The map-type REST data structure containing a dictionary
key	The string keyword to match

Returns: The matching map entry or NULL if the map contains no such entry.

See also: RESP3_MAP; RESP3_ATTRIBUTE; redisxGetMapEntry()

References RedisMap::key, RESP::n, redisxIsMapType(), redisxIsStringType(), and RESP::value.

◆ redisxGetLockedConnectedClient()

RedisClient * redisxGetLockedConnectedClient	(	Redis *	redis,
		enum redisx_channel	channel
	)

Returns the redis client for a given connection type in a Redis instance, with the exclusive access lock if the client is valid and is connected, or else NULL. It is effectively the combination of redisxGetClient() followed by redisxLockConnected().

Parameters

redis	Pointer to a Redis instance.
channel	REDISX_INTERACTIVE_CHANNEL, REDISX_PIPELINE_CHANNEL, or REDISX_SUBSCRIPTION_CHANNEL

Returns: The locked client, if it is enabled, or NULL if the redis argument is NULL, the channel is invalid, or the requested client is not currently connected.

See also: redisxGetClient(); redisxUnlockClient(); redisxLockConnected()

References redisxGetClient(), redisxLockConnected(), X_SUCCESS, and x_trace_null().

◆ redisxGetMapEntry()

RedisMap * redisxGetMapEntry	(	const RESP *	map,
		const RESP *	key
	)

Retrieves a keyed entry from a map-type RESP data structure.

Parameters

map	The map-type REST data structure containing a dictionary
key	The RESP key to match

Returns: The matching map entry or NULL if the map contains no such entry.

See also: RESP3_MAP; RESP3_ATTRIBUTE; redisxGetKeywordEntry()

References RedisMap::key, RESP::n, redisxIsMapType(), RESP::type, and RESP::value.

◆ redisxGetProtocol()

enum redisx_protocol redisxGetProtocol ( Redis * redis )

Returns the actual protocol used with the Redis server. If HELLO was used during connection it will be the protocol that was confirmed in the response of HELLO (and which hopefully matches the protocol requested). Otherwise, RedisX will default to RESP2.

Parameters

redis The Redis server instance

Returns: REDISX_RESP2 or REDISX_RESP3, or else an error code, such as X_NULL (errno = EINVAL) if the argument is NULL, or X_NO_INIT (errno = ENXIO) if the Redis server instance was not initialized.

See also: redisxSetProtocol()

◆ redisxGetScanCount()

int redisxGetScanCount ( Redis * redis )

Returns the COUNT parameter currently set to be used with Redis SCAN-type commands

Parameters

redis Pointer to a Redis instance.

Returns: The current COUNT to use for SCAN-type commands, or <0 in case of an error.

See also: redisxGetScanCount(); redisxScanKeys(); redisxScanTable()

◆ redisxGetStringValue()

char * redisxGetStringValue	(	Redis *	redis,
		const char *	table,
		const char *	key,
		int *	len
	)

Retrieve a variable from Redis as a string (or byte array), through the interactive connection. This is not the highest throughput mode (that would be sending asynchronous pipeline request, and then asynchronously collecting the results such as with redisxSendRequestAsync() / redisxReadReplyAsync()), because it requires separate network roundtrips for each and every request. But, it is simple and perfectly good method when one needs to retrieve only a few (<1000) variables per second...

The call effectively implements a Redis GET (if the table argument is NULL) or HGET call.

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	table	Hashtable from which to retrieve a value or NULL if to use the global table.
[in]	key	Field name (i.e. variable name).
[out]	len	(optional) pointer in which to return the length (>=0) of the value or else an error code (<0) defined in xchange.h / redisx.h

Returns: A freshly allocated RESP array containing the Redis response, or NULL if no valid response could be obtained.

See also: redisxGetValue()

References RESP::n, redisxCheckRESP(), redisxDestroyRESP(), redisxGetValue(), RESP_BULK_STRING, RESP::value, X_SUCCESS, and x_trace_null().

◆ redisxGetTable()

RedisEntry * redisxGetTable	(	Redis *	redis,
		const char *	table,
		int *	n
	)

Returns all the key/value pairs stored in a given hash table

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	table	Hashtable from which to retrieve a value or NULL if to use the global table.
[out]	n	Pointer to the integer in which the number of elements or an error (<0) is returned. It may return an error value from redisxRequest(), or:

REDIS_NULL If got a null or empty response from Redis UNEXPECTED_RESP If the response from Redis was not the expected array type

Returns: A table of all entries (key/value pairs) from this table or NULL if there was an error (see parameter n).

See also: redisxScanTable(); redisxDEstroyEntries()

References RedisMap::key, RedisEntry::key, RESP::n, redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP3_MAP, RESP_ARRAY, RESP::type, RESP::value, RedisMap::value, RedisEntry::value, x_error(), X_GROUP_INVALID, and x_trace_null().

◆ redisxGetTime()

int redisxGetTime	(	Redis *	redis,
		struct timespec *	t
	)

Returns the current time on the Redis server instance.

Parameters

	redis	Pointer to a Redis instance.
[out]	t	Pointer to a timespec structure in which to return the server time.

Returns: X_SUCCESS (0) if successful, or X_NULL if either argument is NULL, or X_PARSE_ERROR if could not parse the response, or another error returned by redisxCheckRESP().

References redisxCheckDestroyRESP(), redisxCheckRESP(), redisxDestroyRESP(), redisxRequest(), RESP_ARRAY, RESP_BULK_STRING, RESP::value, x_error(), X_NULL, X_PARSE_ERROR, X_SUCCESS, and x_trace().

◆ redisxGetValue()

RESP * redisxGetValue	(	Redis *	redis,
		const char *	table,
		const char *	key,
		int *	status
	)

Retrieve a variable from Redis (as an undigested RESP), through the interactive connection. This is not the highest throughput mode (that would be sending asynchronous pipeline request, and then asynchronously collecting the results such as with redisxSendRequestAsync() / redisxReadReplyAsync()), because it requires separate network roundtrips for each and every request. But, it is simple and perfectly good method when one needs to retrieve only a few (<1000) variables per second...

The call effectively implements a Redis GET (if the table argument is NULL) or HGET call.

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	table	Hashtable from which to retrieve a value or NULL if to use the global table.
[in]	key	Field name (i.e. variable name).
[out]	status	(optional) pointer to the return error status, which is either X_SUCCESS on success or else the error code set by redisxArrayRequest(). It may be NULL if not required.

Returns: A freshly allocated RESP containing the Redis response, or NULL if no valid response could be obtained. Values are returned as RESP_BULK_STRING (count = 1), or else type RESP_ERROR or RESP_NULL if Redis responded with an error or null, respectively.

See also: redisxGetStringValue()

References redisxRequest(), x_error(), X_GROUP_INVALID, X_NAME_INVALID, X_SUCCESS, and x_trace_null().

◆ redisxHasComponents()

boolean redisxHasComponents ( const RESP * r )

Checks if a RESP has subcomponents, such as arrays or maps (dictionaries).

Parameters

r	Pointer to a RESP data structure

Returns: TRUE (1) if the data has sub-components, or else FALSE (0).

See also: redisxIsArrayType(); redisxIsMapType(); RESP3_MAP; RESP3_ATTRIBUTE

References FALSE, RESP::n, redisxIsArrayType(), and redisxIsMapType().

◆ redisxHasPipeline()

boolean redisxHasPipeline ( Redis * redis )

Checks if a Redis instance has the pipeline connection enabled.

Parameters

redis Pointer to a Redis instance.

Returns: TRUE (1) if the pipeline client is enabled on the Redis intance, or FALSE (0) otherwise.

References Redis::pipeline, redisxCheckValid(), redisxLockClient(), and redisxUnlockClient().

◆ redisxIgnoreReplyAsync()

int redisxIgnoreReplyAsync ( RedisClient * cl )

Silently consumes a reply from the specified Redis channel. This function should be called with an exclusive lock on a connected client.

Parameters

cl	Pointer to a Redis channel.

Returns: X_SUCCESS if a response was successfully consumed, or REDIS_NULL if a valid response could not be obtained.

See also: redisxReadReplyAsync(); redisxGetLockedConnected()

References REDIS_NULL, redisxDestroyRESP(), redisxReadReplyAsync(), X_SUCCESS, and x_trace().

◆ redisxInit()

Redis * redisxInit ( const char * server )

Initializes the Redis client library, and sets the hostname or IP address for the Redis server.

Parameters

server Server host name or numeric IP address, e.g. "127.0.0.1". The string will be copied, not referenced, for the internal configuration, such that the string passed may be destroyed freely after the call.

Returns: X_SUCCESS or X_FAILURE if the IP address is invalid. X_NULL if the IP address is NULL.

See also: redisxInitSentinel()

References FALSE, Redis::interactive, Redis::pipeline, REDISX_CHANNELS, REDISX_DEFAULT_TIMEOUT_MILLIS, REDISX_INTERACTIVE_CHANNEL, REDISX_PIPELINE_CHANNEL, REDISX_RESP2, REDISX_SUBSCRIPTION_CHANNEL, REDISX_TCP_BUF_SIZE, rSetServerAsync(), Redis::subscription, TRUE, x_error(), X_SUCCESS, and x_trace_null().

◆ redisxInitSentinel()

Redis * redisxInitSentinel	(	const char *	serviceName,
		const RedisServer *	serverList,
		int	nServers
	)

Initializes a Redis client with a Sentinel configuration of alternate servers, and the default sentinel node connection timeout.

Parameters

serviceName	The service name as registered in the Sentinel server configuration. The supplied name will be copied, not referenced, so that the value passed may be freely destroyed after the call.
serverList	An set of Sentinel servers to use to dynamically find the current master. The list itself and its contents are not referenced. Instead a deep copy will be made of it, so the list that was pased can be freely destroyed after the call.
nServers	The number of servers in the list

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetSentinelTimeout(); redisxInit(); redisxConnect()

References REDISX_DEFAULT_SENTINEL_TIMEOUT_MILLIS, redisxInit(), redisxValidateSentinel(), x_error(), X_SUCCESS, x_trace_null(), and xStringCopyOf().

◆ redisxIsArrayType()

boolean redisxIsArrayType ( const RESP * r )

Checks if a RESP holds an array of RESP pointers, and whose value can be cast to (RESP **) to use.

Parameters

r	Pointer to a RESP data structure

Returns: TRUE (1) if the data holds an array of RESP * pointers, or else FALSE (0).

See also: redisxIsScalarType(); redisxIsStringType(); redisxIsMapType(); RESP_ARRAY; RESP3_SET; RESP3_PUSH

References FALSE, RESP3_PUSH, RESP3_SET, RESP_ARRAY, TRUE, and RESP::type.

◆ redisxIsConnected()

boolean redisxIsConnected ( Redis * redis )

Checks if a Redis instance is connected.

Parameters

redis Pointer to a Redis instance.

Returns: TRUE (1) if the Redis instance is connected, or FALSE (0) otherwise.

References FALSE, Redis::interactive, redisxCheckValid(), and X_SUCCESS.

◆ redisxIsEqualRESP()

boolean redisxIsEqualRESP	(	const RESP *	a,
		const RESP *	b
	)

Checks if two RESP are equal, that is they hold the same type of data, have the same 'n' value, and the values match byte-for-byte, or are both NULL.

Parameters

a	Ponter to a RESP data structure.
b	Pointer to another RESP data structure.

Returns: TRUE (1) if the two RESP structures match, or else FALSE (0).

References FALSE, RESP::n, TRUE, RESP::type, and RESP::value.

◆ redisxIsGlobPattern()

int redisxIsGlobPattern ( const char * str )

Checks if a given string is a glob-style pattern.

Parameters

str	The string to check.

Returns: TRUE if it is a glob pattern (e.g. has '*', '?' or '['), otherwise FALSE.

References FALSE, and TRUE.

◆ redisxIsMapType()

boolean redisxIsMapType ( const RESP * r )

Checks if a RESP holds a dictionary, and whose value can be cast to (RedisMap *) to use.

Parameters

r	Pointer to a RESP data structure

Returns: TRUE (1) if the data holds a dictionary (a RedisMap array), or else FALSE (0).

See also: redisxIsScalarType(); redisxIsStringType(); redisxIsMapType(); RESP3_MAP; RESP3_ATTRIBUTE

References FALSE, RESP3_ATTRIBUTE, RESP3_MAP, TRUE, and RESP::type.

◆ redisxIsScalarType()

boolean redisxIsScalarType ( const RESP * r )

Checks if a RESP holds a scalar type value, such as an integer, a boolean or a double-precision value, or a null value.

Parameters

r	Pointer to a RESP data structure

Returns: TRUE (1) if the data holds a scalar-type value, or else FALSE (0).

See also: redisxIsStringType(); redisxIsArrayType(); redisxIsMapType(); RESP_INT; RESP3_BOOLEAN; RESP3_DOUBLE; RESP3_NULL

References FALSE, RESP3_BOOLEAN, RESP3_DOUBLE, RESP3_NULL, RESP_INT, TRUE, and RESP::type.

◆ redisxIsStringType()

boolean redisxIsStringType ( const RESP * r )

Checks if a RESP holds a string type value, whose value can be cast to (char *) to use.

Parameters

r	Pointer to a RESP data structure

Returns: TRUE (1) if the data holds a string type value, or else FALSE (0).

See also: redisxIsScalarType(); redisxIsArrayType(); redisxIsMapType(); RESP_SIMPLE_STRING; RESP_ERROR; RESP_BULK_STRING; RESP3_BLOB_ERROR; RESP3_VERBATIM_STRING

References FALSE, RESP3_BIG_NUMBER, RESP3_BLOB_ERROR, RESP3_VERBATIM_STRING, RESP_BULK_STRING, RESP_ERROR, RESP_SIMPLE_STRING, TRUE, and RESP::type.

◆ redisxIsVerbose()

boolean redisxIsVerbose ( )

Checks id verbose reporting is enabled.

Returns: TRUE if verbose reporting is enabled, otherwise FALSE.

References xIsVerbose().

◆ redisxLoadScript()

int redisxLoadScript	(	Redis *	redis,
		const char *	script,
		char **	sha1
	)

Loads a LUA script into Redis, returning its SHA1 hash to use as it's call ID.

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	script	String containing the full LUA script.
[out]	sha1	Buffer into which SHA1 key returned by Redis to use as call ID. (It must be at least 41 bytes, and will be string terminated). By default it will return an empty string.

Returns: X_SUCCESS (0) if the script has been successfully loaded into Redis, or X_NULL if the Redis instance is NULL X_NAME_INVALID if the script is NULL or empty. REDIS_UNEXPECTED_RESP if received a Redis reponse of the wrong type, or an error (<0) returned by redisxRequest().

References redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_BULK_STRING, RESP::value, x_error(), X_NULL, and X_SUCCESS.

◆ redisxLockClient()

int redisxLockClient ( RedisClient * cl )

Get exclusive write access to the specified Redis channel.

Parameters

cl	Pointer to the Redis client instance.

Returns: X_SUCCESS if the exclusive lock for the channel was successfully obtained, or X_FAILURE if pthread_mutex_lock() returned an error, or X_NULL if the client is NULL, or X_NO_INIT if the client was not initialized.

See also: redisxLockConnected(); redisxUnlockClient()

References x_error(), X_FAILURE, and X_SUCCESS.

◆ redisxLockConnected()

int redisxLockConnected ( RedisClient * cl )

Lock a channel, but only if it has been enabled for communication.

Parameters

cl	Pointer to the Redis client instance

Returns: X_SUCCESS (0) if an excusive lock to the channel has been granted, or X_FAILURE if pthread_mutex_lock() returned an error, or X_NULL if the client is NULL, or X_NO_INIT if the client was not initialized.

See also: redisxLockClient(); redisxUnlockClient(); redisxGetLockedConnectedClient()

References redisxLockClient(), redisxUnlockClient(), x_error(), X_NO_SERVICE, and X_SUCCESS.

◆ redisxMultiSet()

int redisxMultiSet	(	Redis *	redis,
		const char *	table,
		const RedisEntry *	entries,
		int	n,
		boolean	confirm
	)

Sets multiple key/value pairs in a given hash table.

Parameters

redis	Pointer to a Redis instance.
table	Hashtable from which to retrieve a value.
entries	Pointer to an array of key/value pairs.
n	Number of entries.
confirm	Whether we should get a confirmation from the server (requires a round-trip).

Returns: X_SUCCESS (0) on success or an error code (<0) from redisx.h / xchange.h.

References Redis::interactive, REDIS_UNEXPECTED_RESP, redisxArrayRequest(), redisxCheckValid(), redisxDestroyRESP(), redisxMultiSetAsync(), RESP::value, x_error(), X_FAILURE, X_SUCCESS, and x_trace().

◆ redisxMultiSetAsync()

int redisxMultiSetAsync	(	RedisClient *	cl,
		const char *	table,
		const RedisEntry *	entries,
		int	n,
		boolean	confirm
	)

Sets multiple key/value pairs in a given hash table. This function should be called with exclusive access to the client.

Parameters

cl	A Redis client to which we have exclusive access.
table	Hashtable from which to retrieve a value.
entries	Pointer to an array of key/value pairs.
n	Number of entries.
confirm	Whether we should get a confirmation from the server (requires a round-trip).

Returns: X_SUCCESS (0) on success or an error code (<0) from redisx.h / xchange.h.

See also: redisxMultiSet(); redisxLockClient()

References redisxSendArrayRequestAsync(), redisxSkipReplyAsync(), X_FAILURE, X_SUCCESS, and x_trace().

◆ redisxNotify()

int redisxNotify	(	Redis *	redis,
		const char *	channel,
		const char *	message
	)

Sends a regular string terminated Redis PUB/SUB message on the specified channel. Same as redisxPublish() with the length argument set to the length of the string message. Redis must be connected before attempting to send messages.

Parameters

redis	Pointer to a Redis instance.
channel	Redis PUB/SUB channel on which to notify
message	Message to send.

Returns: X_SUCCESS if the message was successfullt sent. X_NO_INIT if the Redis library was not initialized via initRedis(). X_NO_SERVICE if there was a connection problem. PARSE_ERROR if the Redis response could not be confirmed.

See also: redisxPublish(); redisxPublishAsync(); redisxSubscribe()

References redisxPublish(), and X_SUCCESS.

◆ redisxPing()

int redisxPing	(	Redis *	redis,
		const char *	message
	)

Pings the Redis server (see the Redis PING command), and checks the response.

Parameters

redis	Pointer to a Redis instance.
message	Optional message , or NULL for `PING` without an argument.

Returns: X_SUCCESS (0) if successful, or else an error code (<0) from redisx.h / xchange.h.

References REDIS_UNEXPECTED_RESP, redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_BULK_STRING, RESP_SIMPLE_STRING, RESP::value, x_error(), and X_SUCCESS.

◆ redisxPrintDelimited()

void redisxPrintDelimited	(	const RESP *	resp,
		const char *	delim,
		const char *	groupPrefix
	)

Prints a RESP in raw form using delimiters only.

Parameters

resp	Pointer to a RESP (it may be NULL)
delim	Delimiter between elements
groupPrefix	Prefix in front of arrays and maps

See also: redisxPrintRESP(); redisxPrintJSON()

References RESP::n, redisxPrintDelimited(), RESP3_ATTRIBUTE, RESP3_BIG_NUMBER, RESP3_BLOB_ERROR, RESP3_DOUBLE, RESP3_MAP, RESP3_NULL, RESP3_PUSH, RESP3_SET, RESP3_VERBATIM_STRING, RESP_ARRAY, RESP_BULK_STRING, RESP_ERROR, RESP_INT, RESP_SIMPLE_STRING, RESP::type, and RESP::value.

◆ redisxPrintJSON()

int redisxPrintJSON	(	const char *	name,
		const RESP *	resp
	)

Prints a RESP as a JSON fragmen to the standard output with the specified name

Parameters

name	The name/ID to assign to the RESP
resp	The RESP data to print

Returns: 0

See also: redisxPrintRESP(); redisxPrintDelimited(); redisxRESP2JSON()

References redisxRESP2JSON(), and X_SUCCESS.

◆ redisxPrintRESP()

int redisxPrintRESP ( const RESP * resp )

Prints a RESP to the standard output, in a format that is similar to the one used by the standard redis-cli tool.

Parameters

resp	Pointer to a RESP data structure. (It may be NULL).

Returns: X_SUCCESS (0) if successful or else X_FAILURE if there was an error.

See also: redisxPrintJSON(); redisxPrintDelimited()

References X_FAILURE, and X_SUCCESS.

◆ redisxPublish()

int redisxPublish	(	Redis *	redis,
		const char *	channel,
		const char *	data,
		int	length
	)

Sends a generic Redis PUB/SUB message on the specified channel. Redis must be connected before attempting to send messages. It will send the message over the pipeline client if it is avaiable, or else over the interactive client.

Parameters

redis	Pointer to a Redis instance.
channel	Redis PUB/SUB channel on which to notify
data	Data to send.
length	Bytes of data to send, or 0 to determine automatically with strlen().

Returns: X_SUCCESS if the message was successfullt sent. X_NO_INIT if the Redis library was not initialized via initRedis(). X_NO_SERVICE if there was a connection problem. PARSE_ERROR if the Redis response could not be confirmed.

See also: redisxNotify(); redisxPublishAsync(); redisxSubscribe()

References Redis::id, Redis::interactive, redisxCheckValid(), redisxLockConnected(), redisxPublishAsync(), redisxUnlockClient(), X_SUCCESS, and xvprintf.

◆ redisxPublishAsync()

int redisxPublishAsync	(	Redis *	redis,
		const char *	channel,
		const char *	data,
		int	length
	)

Sends a Redis notification asynchronously using the Redis "PUBLISH" command. The caller should have an exclusive lock on the interactive Redis channel before calling this.

Parameters

redis	Pointer to a Redis instance.
channel	Redis PUB/SUB channel on which to notify
data	Message body data.
length	Bytes of message data to send, ot 0 to determine automatically with strlen().

Returns: X_SUCCESS (0) if successful, or else X_NULL if the redis instance is NULL X_NAME_INVALID if the PUB/SUB channel is null or empty or an error code (<0) returned by redisxSendArrayRequestAsync().

See also: redisxPublish(); redisxNotify()

References Redis::interactive, redisxCheckValid(), redisxSendArrayRequestAsync(), redisxSkipReplyAsync(), x_error(), X_NULL, and X_SUCCESS.

◆ redisxReadReplyAsync()

RESP * redisxReadReplyAsync	(	RedisClient *	cl,
		int *	pStatus
	)

Reads a response from Redis and returns it. It should be used with an exclusive lock on a connected client, to collect responses for requests sent previously. It is up to the caller to keep track of what request the response is for. The responses arrive in the same order (and same nummber) as the requests that were sent out.

To follow cluster MOVED or ASK redirections, the caller should check the reponse for redirections (e.g. via redisxIsRedirected()) and then act accordingly to re-submit the corresponding request, as is or with an ASKING directive to follow the redirection.

Parameters

cl	Pointer to a Redis channel
pStatus	Pointer to int in which to return an error status, or NULL if not required.

Returns: The RESP structure for the reponse received from Redis, or NULL if an error was encountered (errno will be set to describe the error, which may either be an errno produced by recv() or EBADMSG if the message was corrupted and/or unparseable. If the error is irrecoverable i.e., other than a timeout, the client will be disabled.)

See also: redisxIgnoreReplyAsync(); redisxSetReplyTimeout(); redisxGetAvailableAsync(); redisxSendRequestAsync(); redisxSendArrayRequestAsync(); redisxGetLockedConnected(); redisxCheckRESP(); redisxIsRedirected()

References FALSE, RedisMap::key, RESP::n, rCloseClientAsync(), REDIS_INCOMPLETE_TRANSFER, REDIS_SIMPLE_STRING_SIZE, REDIS_UNEXPECTED_RESP, redisxAppendRESP(), redisxClusterMoved(), redisxDestroyRESP(), redisxHasComponents(), redisxReadReplyAsync(), RESP3_ATTRIBUTE, RESP3_BIG_NUMBER, RESP3_BLOB_ERROR, RESP3_BOOLEAN, RESP3_CONTINUED, RESP3_DOUBLE, RESP3_MAP, RESP3_NULL, RESP3_PUSH, RESP3_SET, RESP3_VERBATIM_STRING, RESP_ARRAY, RESP_BULK_STRING, RESP_ERROR, RESP_INT, RESP_SIMPLE_STRING, TRUE, RESP::type, RESP::value, RedisMap::value, x_error(), X_FAILURE, X_NO_INIT, X_NO_SERVICE, X_PARSE_ERROR, X_SUCCESS, x_trace_null(), xParseDouble(), and xStringCopyOf().

◆ redisxReconnect()

int redisxReconnect	(	Redis *	redis,
		boolean	usePipeline
	)

Disconnects from Redis, and then connects again...

Parameters

redis	Pointer to a Redis instance.
usePipeline	Whether to reconnect in pipelined mode.

Returns: X_SUCCESS (0) if successful X_NULL if the Redis instance is NULL

or else an error (<0) as would be returned by redisxConnect().

References X_SUCCESS.

◆ redisxRemoveConnectHook()

int redisxRemoveConnectHook	(	Redis *	redis,
		void()(Redis )	setupCall
	)

Removes a connect call hook.

Parameters

redis	Pointer to a Redis instance.
setupCall	User-specified callback routine to be called after the Redis instance has been connected.

Returns: X_SUCCESS (0) if successful or else X_NULL if either of the arguments is NULL.

References x_error(), X_NULL, X_SUCCESS, and xvprintf.

◆ redisxRemoveDisconnectHook()

int redisxRemoveDisconnectHook	(	Redis *	redis,
		void()(Redis )	cleanupCall
	)

Removes a cleanup call hook for when the Redis instance is disconnected.

Parameters

redis	Pointer to a Redis instance.
cleanupCall	User specified function to call when Redis is disconnected.

Returns: X_SUCCESS (0) if successful or else X_NULL if the argument is NULL.

References x_error(), X_NULL, X_SUCCESS, and xvprintf.

◆ redisxRemoveSubscribers()

int redisxRemoveSubscribers	(	Redis *	redis,
		RedisSubscriberCall	f
	)

Removes all instances of a subscribe consumer function from the current list of consumers. This calls only deactivates the specified processing callback function(s), without stopping the delivery of associated messages. To stop Redis sending messages that are no longer being processed, you should also call redisxUnsubscribe() as appropriate.

Parameters

redis	Pointer to a Redis instance.
f	The consumer function to remove from the list of active subscribers.

Returns: The number of instances of f() that have been removed from the list of subscribers.

See also: redisxAddSubscriber(); redisxClearSubscribers(); redisxUnsubscrive()

References x_error(), X_NULL, and xvprintf.

◆ redisxRequest()

RESP * redisxRequest	(	Redis *	redis,
		const char *	command,
		const char *	arg1,
		const char *	arg2,
		const char *	arg3,
		int *	status
	)

Returns the result of a Redis command with up to 3 regularly terminated string arguments. This is not the highest throughput mode (that would be sending asynchronous pipeline request, and then asynchronously collecting the results such as with redisxSendRequestAsync() / redisxReadReplyAsync(), because it requires separate network roundtrips for each and every request. But, it is simple and perfectly good method when one needs to retrieve only a few (<1000) variables per second...

To make Redis calls with binary (non-string) data, you can use redisxArrayRequest() instead, where you can set the number of bytes for each argument explicitly.

Parameters

redis	Pointer to a Redis instance.
command	Redis command, e.g. "HGET"
arg1	First terminated string argument or NULL.
arg2	Second terminated string argument or NULL.
arg3	Third terminated string argument or NULL.
status	Pointer to the return error status, which is either X_SUCCESS on success or else the error code set by redisxArrayRequest().

Returns: A freshly allocated RESP array containing the Redis response, or NULL if no valid response could be obtained or status is not X_SUCCESS.

See also: redisxArrayRequest(); redisxSendRequestAsync(); redisxReadReplyAsync()

References redisxArrayRequest(), redisxDestroyRESP(), X_SUCCESS, and x_trace_null().

◆ redisxRESP2JSON()

char * redisxRESP2JSON	(	const char *	name,
		const RESP *	resp
	)

Converts a RESP to the xchange representation as an appropriate XField.

Parameters

name	The name to assign to the field
resp	The RESP data to convert

Returns: An XField with the data from the RESP, or NULL if there was an error (errno will be set to indicate the type of error).

See also: redisxRESP2XField(); redisxPrintJSON()

References redisxRESP2XField(), and xjsonFieldToString().

◆ redisxRESP2XField()

XField * redisxRESP2XField	(	const char *	name,
		const RESP *	resp
	)

Converts a RESP to the xchange representation as an appropriate XField.

RESP3_NULL values are converted to NULL.
Scalar values are converted to an XField with the equivalent type.
Homogenerous arrays are converted to a field with a 1D array of corresponding xchange type.
Heterogeneous arrays are converted to a field with a 1D array of X_FIELD type (containing an array of fields).
Maps with string keywords are converted to an X_STRUCT.
Maps with non-string keywords are added under a sub-structure named '.non-string-keys' as indexed structures with separate 'key' and 'value' fields.
The original RESP type (single character) is preserved as a 0-terminated string in XField.subtype field.

Parameters

name	The name to assign to the field
resp	The RESP data to convert

Returns: An XField with the data from the RESP, or NULL if there was an error (errno will be set to indicate the type of error).

See also: redisxRESP2JSON()

References RESP::n, RESP3_ATTRIBUTE, RESP3_BIG_NUMBER, RESP3_BLOB_ERROR, RESP3_BOOLEAN, RESP3_DOUBLE, RESP3_MAP, RESP3_NULL, RESP3_PUSH, RESP3_SET, RESP3_VERBATIM_STRING, RESP_ARRAY, RESP_BULK_STRING, RESP_ERROR, RESP_INT, RESP_SIMPLE_STRING, RESP::type, RESP::value, X_UNKNOWN, xCreateBooleanField(), xCreateDoubleField(), xCreateIntField(), xCreateScalarField(), and xCreateStringField().

◆ redisxRunScript()

RESP * redisxRunScript	(	Redis *	redis,
		const char *	sha1,
		const char **	keys,
		const char **	params,
		int *	status
	)

Runs a LUA script that has been loaded into the Redis database, returning the response received, or NULL if there was an error.

Parameters

redis	The Redis instance
sha1	The SHA1 sum of the script that was previously loaded into the Redis DB.
keys	A NULL-terminated array of Redis keywords, or NULL if the script does not take any keyword argument.
params	A NULL-terminated array of additional parameters to pass onto the script, or NULL if the script does not take any parameters.
status	Pointer to int in which to return status, or NULL if not required.

Returns: The response received from the script or the EVALSHA request, or NULL if there was an error.

See also: redisxRunScriptAsync(); redisxLoadScript()

References redisxArrayRequest(), redisxCheckValid(), x_error(), X_NULL, X_SUCCESS, and x_trace_null().

◆ redisxScanKeys()

char ** redisxScanKeys	(	Redis *	redis,
		const char *	pattern,
		int *	n
	)

Returns an alphabetical list of the Redis keys using the Redis SCAN command. Because it uses the scan command, it is guaranteed to not hog the database for excessive periods, and hence it is preferable to redisxGetKeys(table=NULL).

Some data may be returned even if there was an error, and the caller is responsible for cleaning up the returned srotage elements.

The caller may adjust the amount of work performed in each scan call via the redisxSetScanCount() function, prior to calling this.

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	pattern	keyword pattern to match, or NULL for all keys.
[out]	n	Pointer to the integer in which the number of elements (>=0), or else an error code (<0), such as:

X_NULL If one of the arguments is NULL REDIS_NULL If got a null or empty response from Redis UNEXPECTED_RESP If the response from Redis was not the expected array type lt

Returns: An array with pointers to key names from this table or NULL.

See also: redisxGetKeys(); redisxSetScanCount(); redisxDestroyKeys()

References RESP::n, redisxArrayRequest(), redisxCheckRESP(), redisxDestroyKeys(), redisxDestroyRESP(), redisxGetScanCount(), RESP_ARRAY, RESP_BULK_STRING, SCAN_INITIAL_STORE_CAPACITY, RESP::value, x_error(), X_SUCCESS, x_trace_null(), xStringCopyOf(), and xvprintf.

◆ redisxScanTable()

RedisEntry * redisxScanTable	(	Redis *	redis,
		const char *	table,
		const char *	pattern,
		int *	n
	)

Returns an alphabetical list of the Redis hash table data using the Redis HSCAN command. Because it uses the scan command, it is guaranteed to not hog the database for excessive periods, and hence it is preferable to redisxGetTable().

Some data may be returned even if there was an error, and the caller is responsible for cleaning up the returned srotage elements.

The caller may adjust the amount of work performed in each scan call via the redisxSetScanCount() function, prior to calling this.

Parameters

[in]	redis	Pointer to a Redis instance.
[in]	table	Name of Redis hash table to scan data from
[in]	pattern	keyword pattern to match, or NULL for all keys.
[out]	n	Pointer to the integer in which the number of elements (>=0) or else an error code (<0), such as:

X_NULL if one of the arguments is NULL X_GROUP_INVALID if the table name is empty REDIS_NULL if got a null or empty response from Redis UNEXPECTED_RESP if the response from Redis was not the expected array type

Returns: A RedisEntry[] array or NULL.

See also: redisxGetKeys(); redisxSetScanCount(); redisxDestroyEntries()

References RedisEntry::key, RedisEntry::length, RESP::n, redisxArrayRequest(), redisxCheckRESP(), redisxDestroyEntries(), redisxDestroyRESP(), redisxGetScanCount(), RESP_ARRAY, RESP_BULK_STRING, SCAN_INITIAL_STORE_CAPACITY, RESP::value, RedisEntry::value, x_error(), X_GROUP_INVALID, X_NULL, X_SUCCESS, x_trace_null(), xStringCopyOf(), and xvprintf.

◆ redisxSelectDB()

int redisxSelectDB	(	Redis *	redis,
		int	idx
	)

Switches to another database index on the Redis server. Note that you cannot change the database on an active PUB/SUB channel, hence the call will return X_INCOMPLETE if attempted. You should instead switch DB when there are no active subscriptions.

Parameters

redis	Pointer to a Redis instance.
idx	zero-based database index

Returns: X_SUCCESS (0) if successful, or X_NULL if the redis argument is NULL, X_INCOMPLETE if there is an active subscription channel that cannot be switched or one of the channels could not confirm the switch, or else another error code (<0) from redisx.h / xchange.h.

See also: redisxSelectDB(); redisxLockConnected()

References REDIS_INVALID_CHANNEL, REDISX_CHANNELS, REDISX_PIPELINE_CHANNEL, REDISX_SUBSCRIPTION_CHANNEL, redisxAddConnectHook(), redisxGetClient(), redisxIsConnected(), redisxLockConnected(), redisxRemoveConnectHook(), redisxUnlockClient(), X_INCOMPLETE, X_SUCCESS, and x_trace().

◆ redisxSendArrayRequestAsync()

int redisxSendArrayRequestAsync	(	RedisClient *	cl,
		const char **	args,
		const int *	lengths,
		int	n
	)

Send a Redis request with an arbitrary number of arguments. This function should be called with an exclusive lock on a connected client.

Unlike its interactive counterpart, redisxArrayRequest(), this method does not follow cluster MOVED or ASK redirections automatically. It cannot, since it returns without waiting for a response. To implement redirections, the caller must keep track of the asynchronous requests sent, and check for redirections when processing responses via redisxReadReplyAsync(). If the response is a redirection, then the caller can decide if and how to re-submit the request to follow the redirection.

Parameters

cl	Pointer to the Redis client.
args	The array of string arguments to send. If you have an `char ` array, you may need to cast to `(const char )` to avoid compiler warnings.
lengths	Array indicating the number of bytes to send from each string argument. Zero or negative values can be used to determine the string length automatically using strlen(), and the length argument itself may be NULL to determine the lengths of all string arguments automatically.
n	The number of arguments to send.

Returns: X_SUCCESS (0) on success or X_NULL if the client is NULL, or X_NO_SERVICE if not connected to the client or if send() failed, or X_NO_INIT if the client was not initialized.

See also: redisxSendRequestAsync(); redisxArrayRequest(); redisxReadReplyAsync(); redisxGetLockedConnected(); redisxSkipReplyAsync()

References FALSE, REDISX_CMDBUF_SIZE, TRUE, x_error(), X_NO_SERVICE, X_SUCCESS, and xvprintf.

◆ redisxSendRequestAsync()

int redisxSendRequestAsync	(	RedisClient *	cl,
		const char *	command,
		const char *	arg1,
		const char *	arg2,
		const char *	arg3
	)

Send a command (with up to 3 arguments) to the Redis server. The caller must have an exclusive lock on the client for this version. The arguments supplied will be used up to the first non-NULL value.

Unlike its interactive counterpart, redisxRequest(), this method does not follow cluster MOVED or ASK redirections automatically. It cannot, since it returns without waiting for a response. To implement redirections, the caller must keep track of the asynchronous requests sent, and check for redirections when processing responses via redisxReadReplyAsync(). If the response is a redirection, then the caller can decide if and how to re-submit the request to follow the redirection.

Parameters

cl	Pointer to the Redis client instance.
command	Redis command string.
arg1	Optional first string argument or NULL.
arg2	Optional second string argument or NULL.
arg3	Optional third string argument or NULL.

Returns: X_SUCCESS (0) on success or X_NULL if the client is NULL, or else X_NO_SERVICE if not connected to the client or if send() failed

See also: redisxSendArrayRequestAsync(); redisxRequest(); redisxReadReplyAsync(); redisxGetLockedConnected(); redisxSkipReplyAsync()

References redisxSendArrayRequestAsync(), x_error(), X_NAME_INVALID, and X_SUCCESS.

◆ redisxSetDHCipherParams()

int redisxSetDHCipherParams	(	Redis *	redis,
		const char *	dh_params_file
	)

Sets parameters for DH-based cyphers when using a TLS encrypted connection to Redis.

Parameters

redis	A Redis instance.
dh_params_file	Path to the DH-based cypher parameters file (in PEM format; we don't support the old DER format), or NULL for no params.

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetTLS(); redisxSetTLSCiphers()

References x_error(), X_FAILURE, X_SUCCESS, and xStringCopyOf().

◆ redisxSetHostname()

int redisxSetHostname	(	Redis *	redis,
		const char *	host
	)

Changes the host name for the Redis server, prior to calling redisxConnect().

Parameters

redis	Pointer to a Redis instance.
host	New host name or IP address to use.

Returns: X_SUCCESS (0) if successful, or else X_NULL if the redis instance or the host name is NULL, or X_NO_INIT if the redis instance is not initialized, X_ALREADY_OPEN if the redis instance is currently in a connected state, or X_FAILURE if Redis was initialized in Sentinel configuration.

See also: redisxSetPort(); redisxConnect()

References redisxIsConnected(), rSetServerAsync(), X_ALREADY_OPEN, x_error(), X_FAILURE, X_NULL, and X_SUCCESS.

◆ redisxSetMutualTLS()

int redisxSetMutualTLS	(	Redis *	redis,
		const char *	cert_file,
		const char *	key_file
	)

Set a TLS certificate and private key for mutual TLS. You will still need to call redisxSetTLS() also to create a complete TLS configuration. Redis normally uses mutual TLS, which requires both the client and the server to authenticate themselves. For this you need the server's TLS certificate and private key also. It is possible to configure Redis servers to verify one way only with a CA certificate, in which case you don't need to call this to configure the client.

To disable mutual TLS, set both file name arguments to NULL.

Parameters

redis	A Redis instance.
cert_file	Path to the server's certificate file.
key_file	Path to the server'sprivate key file.

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetTLS()

References x_error(), X_FAILURE, X_NULL, X_SUCCESS, and xStringCopyOf().

◆ redisxSetPassword()

int redisxSetPassword	(	Redis *	redis,
		const char *	passwd
	)

Sets the password to use for authenticating on the Redis server after connection. See the AUTH Redis command for more explanation. Naturally, you need to call this prior to connecting your Redis instance to have the desired effect.

Parameters

redis	Pointer to the Redis instance for which to set credentials
passwd	the password to use for authenticating on the server, or NULL to clear a previously configured password.

Returns: X_SUCCESS (0) if successful, X_NULL if the redis argument is NULL, or X_ALREADY_OPEN if called after Redis was already connected.

See also: redisxSetUser()

References redisxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

◆ redisxSetPipelineConsumer()

int redisxSetPipelineConsumer	(	Redis *	redis,
		RedisPipelineProcessor	f
	)

Sets the function processing valid pipeline responses. The implementation should follow a simple set of rules:

the implementation should not destroy the RESP data. The RESP will be destroyed automatically after the call returns. However, the call may retain any data from the RESP itself, provided the data is de-referenced from the RESP before return.
The implementation should not block (aside from maybe a quick mutex unlock) and return quickly, so as to not block the client for long periods
If extensive processing or blocking calls are required to process the message, it is best to simply place a copy of the RESP on a queue and then return quickly, and then process the message asynchronously in a background thread.

Parameters

redis	Pointer to a Redis instance.
f	The function that processes a single argument of type RESP pointer.

Returns: X_SUCCESS (0) if successful, or X_NULL if the Redis instance is NULL.

References X_SUCCESS.

◆ redisxSetPort()

int redisxSetPort	(	Redis *	redis,
		int	port
	)

Sets a non-standard TCP port number to use for the Redis server, prior to calling redisxConnect().

Parameters

redis	Pointer to a Redis instance.
port	The TCP port number to use.

Returns: X_SUCCESS (0) if successful, or else X_NULL if the redis instance is NULL, or X_NO_INIT if the redis instance is not initialized, X_ALREADY_OPEN if the Redis instance is lready connected to a server, or X_FAILURE if Redis was initialized in Sentinel configuration.

See also: redisxSetHostname(); redisxConnect()

References redisxIsConnected(), X_ALREADY_OPEN, x_error(), X_FAILURE, and X_SUCCESS.

◆ redisxSetProtocol()

int redisxSetProtocol	(	Redis *	redis,
		enum redisx_protocol	protocol
	)

Sets the RESP prorocol version to use for future client connections. The protocol is set with the HELLO command, which was introduced in Redis 6.0.0 only. For older Redis server instances, the protocol will default to RESP2. Calling this function will enable using HELLO to handshake with the server.

Parameters

redis	The Redis server instance
protocol	REDISX_RESP2 or REDISX_RESP3.

Returns: X_SUCCESS (0) if successful, or X_NULL if the redis argument in NULL, X_NO_INIT if the redis instance was not initialized.

See also: redisxGetProtocol(); redisxGetHelloReply()

References TRUE, and X_SUCCESS.

◆ redisxSetPushProcessor()

int redisxSetPushProcessor	(	Redis *	redis,
		RedisPushProcessor	func,
		void *	arg
	)

Sets a user-defined function to process push messages for a specific Redis instance. The function's implementation must follow a simple set of rules:

the implementation should not destroy the RESP data. The RESP will be destroyed automatically after the call returns. However, the call may retain any data from the RESP itself, provided the data is de-referenced from the RESP before return.
The call will have exclusive access to the client. As such it should not try to obtain a lock or release the lock itself.
The implementation should not block (aside from maybe a quick mutex unlock) and return quickly, so as to not block the client for long periods
If extensive processing or blocking calls are required to process the message, it is best to simply place a copy of the RESP on a queue and then return quickly, and then process the message asynchronously in a background thread.
The client on which the push is originated will be locked, thus the implementation should avoid getting explusive access to the client

Parameters

redis	Redis instance
func	Function to use for processing push messages from the given Redis instance, or NULL to ignore push messages.
arg	(optional) User-defined pointer argument to pass along to the processing function.

Returns: X_SUCCESS (0) if successful, or else X_NULL (errno set to EINVAL) if the client argument is NULL, or X_NO_INIT (errno set to EAGAIN) if redis is uninitialized.

References X_SUCCESS.

◆ redisxSetReplyTimeout()

int redisxSetReplyTimeout	(	Redis *	redis,
		int	timeoutMillis
	)

Set a timeout for getting replies on the interactive client. This does not affect the pipeline and subscription clients, which do not have a timeout (appropriately for asynchronous processing)

Parameters

redis	Pointer to a Redis instance.
timeoutMillis	[ms] timeout for interactive responses, or <0 for indefinite.

Returns: X_SUCCESS (0).

See also: redisxSetSocketTimeout()

References Redis::interactive, and X_SUCCESS.

◆ redisxSetScanCount()

int redisxSetScanCount	(	Redis *	redis,
		int	count
	)

Sets the COUNT parameter to use with Redis SCAN type commands. COUNT specifies how much work Redis should do in a single scan iteration. 0 (or negative) values can be used to scan with defaults (without the COUNT option), which is usually equivalent to COUNT=10. When scanning large datasets, it may take many scan calls to go through all the data. When networking has limited bandwidth, or large latencies it may be desirable to do more work per call on the server side to reduce traffic. However, the cost of larger COUNT values is that it may increase server latencies for other queries.

Parameters

redis	Pointer to a Redis instance.
count	The new COUNT to use for SCAN-type commands or <0 to use default.

See also: redisxGetScanCount(); redisxScanKeys(); redisxScanTable()

References X_SUCCESS.

◆ redisxSetSentinelTimeout()

int redisxSetSentinelTimeout	(	Redis *	redis,
		int	millis
	)

Changes the connection timeout for Sentinel server instances in the discovery phase. This is different from the timeout that is used for the master server, once it is discovered.

Parameters

redis	The Redis instance, which was initialized for Sentinel via redisxInitSentinel().
millis	[ms] The new connection timeout or <=0 to use the default value.

Returns: X_SUCCESS (0) if successfully set sentinel connection timeout, or else X_NULL if the redis instance is NULL, or X_NO_INIT if the redis instance is not initialized for Sentinel.

See also: redisxSetSocketTimeout(); redisxInitSentinel()

References REDISX_DEFAULT_SENTINEL_TIMEOUT_MILLIS, x_error(), X_NO_INIT, and X_SUCCESS.

◆ redisxSetSocketConfigurator()

int redisxSetSocketConfigurator	(	Redis *	redis,
		RedisSocketConfigurator	func
	)

Sets a user-defined callback for additioan custom configuring of client sockets

Parameters

redis	The Redis server instance
func	The user-defined callback function, which performs the additional socket configuration

Returns: X_SUCCESS (0) if successful, or or X_NULL (errno = EINVAL) if the redis argument in NULL, X_NO_INIT (errno = ENXIO) if the redis instance was not initialized.

See also: redisxSetSocketErrorHandler()

References TRUE, and X_SUCCESS.

◆ redisxSetSocketErrorHandler()

int redisxSetSocketErrorHandler	(	Redis *	redis,
		RedisErrorHandler	f
	)

Sets the user-specific error handler to call if a socket level trasmit error occurs. It replaces any prior handlers set earlier.

Parameters

redis The Redis instance to configure.

f The error handler function, which is called with the pointer to the redis instance that had the errror, the redis channel index (e.g. REDIS_INTERACTIVE_CHANNEL) and the operation (e.g. 'send' or 'read') that failed. Note, that the call may be made with the affected Redis channel being in a locked state. As such the handler should not directly attempt to change the connection state of the Redis instance. Any calls that require exlusive access to the affected channel should instead be spawn off into a separate thread, which can obtain the necessary lock when it is released.

Returns: X_SUCCESS if the handler was successfully configured, or X_NULL if the Redis instance is NULL.

See also: redisxSetSocketConfigurator()

References X_SUCCESS.

◆ redisxSetSocketTimeout()

int redisxSetSocketTimeout	(	Redis *	redis,
		int	millis
	)

Sets a socket timeout for future client connections on a Redis instance. Effectively this is a timeout for send() only. The timeout for interatvice replies is controlled separately via redisxSetReplyTimoeut().

If not set (or set to zero or a negative value), then the timeout will not be configured for sockets, and the system default timeout values will apply.

Parameters

redis	The Redis instance
millis	[ms] The desired socket read/write timeout, or <0 for socket default.

Returns: X_SUCCESS (0) if successful, or else X_NULL if the redis instance is NULL, or X_NO_INIT if the redis instance is not initialized.

See also: redisxSetReplyTimeout()

References REDISX_DEFAULT_TIMEOUT_MILLIS, and X_SUCCESS.

◆ redisxSetTcpBuf()

int redisxSetTcpBuf	(	Redis *	redis,
		int	size
	)

Set the size of the TCP/IP buffers (send and receive) for future client connections.

Parameters

redis	Pointer to a Redis instance.
size	(bytes) requested buffer size, or <= 0 to use default value

Returns: X_SUCCESS (0) if successful, or else X_NULL if the redis instance is NULL, or X_NO_INIT if the redis instance is not initialized, or X_FAILURE if Redis was initialized in Sentinel configuration.

References X_SUCCESS.

◆ redisxSetTLS()

int redisxSetTLS	(	Redis *	redis,
		const char *	ca_path,
		const char *	ca_file
	)

Configures a TLS-encrypted connection to Redis with the specified CA certificate file. Normally you will want to set up mutual TLS with redisxSetMutualTLS() also, unless the server is not requiring mutual authentication. Additionally, you might also want to set parameters for DH-based cyphers if needed using redisxSetDHCypherParams().

Parameters

redis	A Redis instance.
ca_path	Directory containing CA certificates. It may be NULL to use the default locations.
ca_file	CA certificate file relative to specified directory. It may be NULL to use default certificate.

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetMutualTLS(); redisxSetDHCipherParams(); redisxSetTLSCiphers(); redisxSetTLSCipherSuites(); redisxSetTLSServerName(); redisxSetTLSVerify()

References TRUE, x_error(), X_FAILURE, X_SUCCESS, and xStringCopyOf().

◆ redisxSetTLSCiphers()

int redisxSetTLSCiphers	(	Redis *	redis,
		const char *	cipher_list
	)

Sets the TLS ciphers to try (TLSv1.2 and earlier).

Parameters

redis	A Redis instance.
cipher_list	a colon (:) separated list of ciphers, or NULL for default ciphers.

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetTLSCipherSuites(); redisxSetTLS(); redisxSetDHCipherParams()

References x_error(), X_FAILURE, X_SUCCESS, and xStringCopyOf().

◆ redisxSetTLSCipherSuites()

int redisxSetTLSCipherSuites	(	Redis *	redis,
		const char *	list
	)

Sets the TLS ciphers suites to try (TLSv1.3 and later).

Parameters

redis	A Redis instance.
list	a colon (:) separated list of cipher suites, or NULL for default cipher suites.

Returns: X_SUCCESS (0) if successful, or else an error code <0.

See also: redisxSetTLSCiphers(); redisxSetTLS(); redisxSetDHCipherParams()

References x_error(), X_FAILURE, X_SUCCESS, and xStringCopyOf().

◆ redisxSetTLSServerName()

int redisxSetTLSServerName	(	Redis *	redis,
		const char *	host
	)

Sets the Server name for TLS Server Name Indication (SNI), an optional extra later of security.

Parameters

redis	A Redis instance.
host	server name to use for SNI.

Returns: X_SUCCESS (0)

See also: redisxSetTLS()

References x_error(), X_FAILURE, X_SUCCESS, and xStringCopyOf().

◆ redisxSetTLSVerify()

int redisxSetTLSVerify	(	Redis *	redis,
		boolean	value
	)

Sets whether to verify the the certificate. Certificates are verified by default.

Parameters

redis	A Redis instance.
value	TRUE (non-zero) to verify certificates, or else FALSE (0)

Returns: X_SUCCESS (0)

See also: redisxSetTLS()

References x_error(), X_FAILURE, and X_SUCCESS.

◆ redisxSetUser()

int redisxSetUser	(	Redis *	redis,
		const char *	username
	)

Sets the user name to use for authenticating on the Redis server after connection. See the AUTH Redis command for more explanation. Naturally, you need to call this prior to connecting your Redis instance to have the desired effect.

Parameters

redis	Pointer to the Redis instance for which to set credentials
username	the password to use for authenticating on the server, or NULL to clear a previously configured password.

Returns: X_SUCCESS (0) if successful, X_NULL if the redis argument is NULL, or X_ALREADY_OPEN if called after Redis was already connected.

See also: redisxSetPassword()

References redisxIsConnected(), X_ALREADY_OPEN, x_error(), X_SUCCESS, and xStringCopyOf().

◆ redisxSetValue()

int redisxSetValue	(	Redis *	redis,
		const char *	table,
		const char *	key,
		const char *	value,
		boolean	confirm
	)

Sets a global or hashtable value on Redis.

Parameters

redis	Pointer to a Redis instance.
table	Hash table identifier or NULL if setting a global value.
key	Redis field name (i.e. variable name).
value	A proper 0-terminated string value to store.
confirm	Whether we should get a confirmation from the server (requires a round-trip).

Returns: X_SUCCESS (0) if the variable was succesfully set, or: X_NO_INIT X_NAME_INVALID X_NULL X_NO_SERVICE X_FAILURE

References FALSE, Redis::interactive, redisxCheckRESP(), redisxDestroyRESP(), redisxLockConnected(), redisxRequest(), redisxSetValueAsync(), redisxUnlockClient(), RESP_INT, x_error(), X_NULL, and X_SUCCESS.

◆ redisxSetValueAsync()

int redisxSetValueAsync	(	RedisClient *	cl,
		const char *	table,
		const char *	key,
		const char *	value,
		boolean	confirm
	)

Sends a request for setting a table value, using the Redis "SET" or "HSET" command.

Parameters

cl	Pointer to a Redis channel.
table	Hashtable from which to retrieve a value or NULL if to use the global table.
key	Field name (i.e. variable name).
value	The string value to set (assumes normal string termination).'
confirm	Whether confirmation is requested from Redis to acknowledge.

Returns: X_SUCCESS (0) if successful, or X_NULL if the client or value is NULL X_NAME_INVALID if key is invalid, or an error (<0) returned by redisxSendRequestAsync().

References redisxSendRequestAsync(), redisxSkipReplyAsync(), x_error(), X_NAME_INVALID, X_NULL, X_SUCCESS, and xvprintf.

◆ redisxSetVerbose()

void redisxSetVerbose ( boolean value )

Enable or disable verbose reporting of all Redis operations (and possibly some details of them). Reporting is done on the standard output (stdout). It may be useful when debugging programs that use the redisx interface. Verbose reporting is DISABLED by default.

Parameters

value TRUE to enable verbose reporting, or FALSE to disable.

See also: redisxDebugTraffic()

References xSetVerbose().

◆ redisxSkipReplyAsync()

int redisxSkipReplyAsync ( RedisClient * cl )

Instructs Redis to skip sending a reply for the next command. This function should be called with an exclusive lock on a connected client, and just before redisxSendRequest() or redisxSendArrayRequestAsync().

Sends CLIENT REPLY SKIP

Parameters

cl	Pointer to the Redis client to use.

Returns: X_SUCCESS (0) on success or X_NULL if the client is NULL, or else X_NO_SERVICE if not connected to the Redis server on the requested channel, or if send() failed, or else X_NO_INIT if the client was not initialized.

See also: redixSendRequestAsync(); redisxSendArrayRequestAsync(); redisxGetLockedConnected()

References TRUE, and X_SUCCESS.

◆ redisxSplitText()

int redisxSplitText	(	RESP *	resp,
		char **	text
	)

Splits the string value of a RESP into two components, by terminating the first component with a null byte and optionally returning the remaining part and length in the output parameters. Only RESP_ERROR RESP_BLOB_ERROR and RESP_VERBATIM_STRING types can be split this way. All others will return REDIS_UNEXPECTED_RESP.

Parameters

	resp	The input RESP.
[out]	text	(optional) pointer in which to return the start of the remnant text component.

Returns: n the length of the remnant text (<=0), or else X_NULL if the input RESP was NULL, or REDIS_UNEXPEXCTED_RESP if the input RESP does not contain a two-component string value.

See also: RESP_ERROR; RESP3_BLOB_ERROR; RESP3_VERBATIM_STRING

References RESP::n, REDIS_UNEXPECTED_RESP, RESP3_BLOB_ERROR, RESP3_VERBATIM_STRING, RESP_ERROR, RESP::type, RESP::value, x_error(), X_NULL, and X_PARSE_ERROR.

◆ redisxStartBlockAsync()

int redisxStartBlockAsync ( RedisClient * cl )

Starts an atomic Redis transaction block, by sending MULTI on the specified client connection. This function should be called with an exclusive lock on a connected client.

Redis transaction blocks behave just like scripts (in fact they are effectively improptu scripts themselves). As such the rules of Redis scripting apply, such as you cannot call LUA from within a transaction block (which is a real pity...)

Once you start a transaction block you may ignore all acknowledgedments such as OK and QUEUED responses that Redis sends back. These will be 'processed' in bulk by redisEndBlockAsync(), at the end of the transaction block.

Parameters

cl	Pointer to a Redis client.

Returns: X_SUCCESS (0) if successful, or X_NULL if the Redis client is NULL, or X_NO_SERVICE if not connected to the client server or if send() failed, or X_NO_INIT if the client was not initialized.

See also: redisxExecBlockAsync(); redisxAbortBlockAsync(); redisxGetLockedConnected()

References TRUE, and X_SUCCESS.

◆ redisxSubscribe()

int redisxSubscribe	(	Redis *	redis,
		const char *	pattern
	)

Subscribe to a specific Redis channel. The call will also start the subscription listener thread to processing incoming subscription messages. Subscribing only enabled the delivery of the messages to this client without any actions on these messages. In order to process the messages for your subscriptons, you will also want to call redisxAddSubscriber() to add your custom processor function(s).

Parameters

redis	Pointer to a Redis instance.
pattern	The Channel pattern to subscribe to, e.g. 'acc1', or 'acc*'...

Returns: X_SUCCESS if successfully subscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server. X_NULL if the channel argument is NULL

See also: redisxAddSubscriber(); redisxUnsubscribe(); redisxNotify(); redisxPublish(); redisxPublishAsync()

References redisxIsGlobPattern(), redisxLockConnected(), redisxSendRequestAsync(), redisxUnlockClient(), Redis::subscription, x_error(), X_NULL, and X_SUCCESS.

◆ redisxUnlockClient()

int redisxUnlockClient ( RedisClient * cl )

Relinquish exclusive write access to the specified Redis channel

Parameters

cl	Pointer to the Redis client instance

Returns: X_SUCCESS if the exclusive lock for the channel was successfully obtained, or X_FAILURE if pthread_mutex_lock() returned an error, or X_NULL if the client is NULL, or X_NO_INIT if the client was not initialized.

See also: redisxLockClient(); redisxLockConnected()

References x_error(), X_FAILURE, and X_SUCCESS.

◆ redisxUnsubscribe()

int redisxUnsubscribe	(	Redis *	redis,
		const char *	pattern
	)

Unsubscribe from one or all Redis PUB/SUB channel(s). If there are no active subscriptions when Redis confirms the unsubscrive command, the subscription listener thread will also conclude automatically. Unsubscribing will stop delivery of mesasages for the affected channels but any associated processing callbacks remain registered, until redisxRemovesubscribers() is called to deactive them as appropriate.

Parameters

redis	Pointer to a Redis instance.
pattern	The channel pattern, or NULL to unsubscribe all channels and patterns.

Returns: X_SUCCESS if successfully subscribed to the Redis distribution channel. X_NO_SERVICE if there is no active connection to the Redis server.

See also: redisxSubscribe(); redisxEndSubscribe(); redisxRemoveSubscribers()

References redisxCheckValid(), redisxIsGlobPattern(), redisxLockConnected(), redisxSendRequestAsync(), redisxUnlockClient(), Redis::subscription, and X_SUCCESS.

◆ redisxValidateSentinel()

int redisxValidateSentinel	(	const char *	serviceName,
		const RedisServer *	serverList,
		int	nServers
	)

Validates a Sentinel configuration.

Parameters

serviceName	The service name as registered in the Sentinel server configuration.
serverList	An set of Sentinel servers to use to dynamically find the current master.
nServers	The number of servers in the list

Returns: X_SUCCESS (0) if successful, or X_NAME_INVALID if the serviceName is NULL or empty, or X_NULL if the serverList is NULL, or X_SIZE_INVALID if nServers is 0 or negative, or else X_GROUP_INVALID if the first server has a NULL or empty host name.

References x_error(), X_GROUP_INVALID, X_NAME_INVALID, X_NULL, X_SIZE_INVALID, and X_SUCCESS.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ REDISX_LISTENER_REL_PRIORITY

◆ REDISX_VERSION_STRING

Typedef Documentation

◆ RedisErrorHandler

◆ RedisPipelineProcessor

◆ RedisPushProcessor

◆ RedisSocketConfigurator

◆ RedisSubscriberCall

Enumeration Type Documentation

◆ redisx_channel

◆ redisx_protocol

◆ resp_type

Function Documentation

◆ redisxAbortBlockAsync()

◆ redisxAddConnectHook()

◆ redisxAddDisconnectHook()

◆ redisxAddSubscriber()

◆ redisxArrayRequest()

◆ redisxCheckDestroyRESP()

◆ redisxCheckRESP()

◆ redisxCheckValid()

◆ redisxClearAttributesAsync()

◆ redisxClearConnectHooks()

◆ redisxClearDisconnectHooks()

◆ redisxClearSubscribers()

◆ redisxClusterAskMigrating()

◆ redisxClusterAskMigratingAsync()

◆ redisxClusterConnect()

◆ redisxClusterDestroy()

◆ redisxClusterDisconnect()

◆ redisxClusterGetRedirection()

◆ redisxClusterGetShard()

◆ redisxClusterInit()

◆ redisxClusterIsMigrating()

◆ redisxClusterIsRedirected()

◆ redisxClusterMoved()

◆ redisxConnect()

◆ redisxCopyOfRESP()

◆ redisxDebugTraffic()

◆ redisxDestroy()

◆ redisxDestroyEntries()

◆ redisxDestroyKeys()

◆ redisxDestroyRESP()

◆ redisxDisconnect()

◆ redisxEndSubscription()

◆ redisxError()

◆ redisxErrorDescription()

◆ redisxExecBlockAsync()

◆ redisxGetAttributes()

◆ redisxGetAttributesAsync()

◆ redisxGetAvailable()

◆ redisxGetAvailableAsync()

◆ redisxGetClient()

◆ redisxGetHelloData()

◆ redisxGetInfo()

◆ redisxGetKeys()

◆ redisxGetKeywordEntry()

◆ redisxGetLockedConnectedClient()

◆ redisxGetMapEntry()

◆ redisxGetProtocol()

◆ redisxGetScanCount()

◆ redisxGetStringValue()

◆ redisxGetTable()

◆ redisxGetTime()

◆ redisxGetValue()

◆ redisxHasComponents()

◆ redisxHasPipeline()

◆ redisxIgnoreReplyAsync()

◆ redisxInit()

◆ redisxInitSentinel()

◆ redisxIsArrayType()

◆ redisxIsConnected()

◆ redisxIsEqualRESP()