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	RedisEntry
	A single key / value entry, or field, in the Redis database. More...

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_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_LISTENER_REL_PRIORITY (0.5)

#define	REDISX_MAJOR_VERSION 0
	API major version.

#define	REDISX_MINOR_VERSION 9
	API minor version.

#define	REDISX_PATCHLEVEL 1
	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	RESP_ARRAY
	RESP array type.

#define	RESP_BULK_STRING
	RESP bulk string type.

#define	RESP_ERROR
	RESP error message type.

#define	RESP_INT
	RESP integer type.

#define	RESP_SIMPLE_STRING
	RESP simple string type.

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

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 }

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, char args[], int length[], int n, int *status)

int	redisxCheckDestroyRESP (RESP *resp, char expectedType, int expectedSize)

int	redisxCheckRESP (const RESP *resp, char expectedType, int expectedSize)

void	redisxClearConnectHooks (Redis *redis)

void	redisxClearDisconnectHooks (Redis *redis)

int	redisxClearSubscribers (Redis *redis)

int	redisxConnect (Redis *redis, boolean usePipeline)

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)

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

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

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

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	redisxHasPipeline (Redis *redis)

int	redisxIgnoreReplyAsync (RedisClient *cl)

Redis *	redisxInit (const char *server)

boolean	redisxIsConnected (Redis *redis)

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)

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	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 **	redisxScanKeys (Redis redis, const char pattern, int n, int status)

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

int	redisxSelectDB (Redis *redis, int idx)

int	redisxSendArrayRequestAsync (RedisClient cl, char args[], int length[], int n)

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

int	redisxSetPassword (Redis redis, const char passwd)

int	redisxSetPipelineConsumer (Redis redis, void(f)(RESP *))

int	redisxSetPort (Redis *redis, int port)

int	redisxSetScanCount (Redis *redis, int count)

void	redisxSetTcpBuf (int size)

int	redisxSetTransmitErrorHandler (Redis *redis, RedisErrorHandler f)

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	redisxStartBlockAsync (RedisClient *cl)

int	redisxSubscribe (Redis redis, const char channel)

int	redisxUnlockClient (RedisClient *cl)

int	redisxUnsubscribe (Redis redis, const char channel)

Detailed Description

Date: May 4, 2018

Author: Attila Kovacs

RedisX public constant, data types and function prototypes.

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.

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.

◆ 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.

Function Documentation

◆ redisxAbortBlockAsync()

int redisxAbortBlockAsync ( RedisClient * cl )

Abort an atomic transaction block. It sends DISCARD.

Parameters

cl	Pointer to a Redis client

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

See also: redisxStartBlockAsync()

References redisxIgnoreReplyAsync(), TRUE, x_error(), X_NULL, 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_error(), X_NULL, X_SUCCESS, x_warn(), xStringCopyOf(), and xvprintf.

◆ redisxArrayRequest()

RESP * redisxArrayRequest	(	Redis *	redis,
		char *	args[],
		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...

Parameters

redis	Pointer to a Redis instance.
args	An array of strings to send to Redis, corresponding to a single query.
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, which is either X_SUCCESS on success. X_NO_INIT if the Redis client librarywas not initialized via initRedis. X_NULL if the argument is NULL or n<1. 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, redisxLockConnected(), redisxReadReplyAsync(), redisxSendArrayRequestAsync(), redisxUnlockClient(), x_error(), X_NULL, X_SUCCESS, x_trace_null(), and xvprintf.

◆ redisxCheckDestroyRESP()

int redisxCheckDestroyRESP	(	RESP *	resp,
		char	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,
		char	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_NULL, REDIS_UNEXPECTED_RESP, RESP_INT, RESP::type, RESP::value, x_error(), X_FAILURE, X_NULL, and X_SUCCESS.

◆ redisxClearConnectHooks()

void redisxClearConnectHooks ( Redis * redis )

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

Parameters

redis Pointer to a Redis instance.

References 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 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 x_error(), X_NULL, and xvprintf.

◆ 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 x_error(), X_NULL, and X_SUCCESS.

◆ 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 REDISX_CHANNELS, redisxDisconnect(), and redisxIsConnected().

◆ redisxDestroyEntries()

void redisxDestroyEntries	(	RedisEntry *	entries,
		int	count
	)

Destroy a RedisEntry array, such as returned e.g. by redisxScanTable()

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 RESP::n, redisxDestroyRESP(), RESP_ARRAY, RESP::type, and RESP::value.

◆ redisxDisconnect()

void redisxDisconnect ( Redis * redis )

Disconnect all clients from the Redis server.

Parameters

redis Pointer to a Redis instance.

◆ 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_error(), X_NULL, and 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 )

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.

Parameters

cl	Pointer to a Redis client

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

See also: redisxStartBlockAsync(); redisxAbortBlockAsync()

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

◆ 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 the channel argument is invalid.

References REDISX_CHANNELS, and x_error().

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

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

◆ 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 to use default.

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

References x_error().

◆ 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_error(), X_NULL, 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 RedisEntry::key, RedisEntry::length, RESP::n, redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_ARRAY, RESP::value, RedisEntry::value, x_error(), X_GROUP_INVALID, X_NULL, 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 array containing the Redis response, or NULL if no valid response could be obtained.

See also: redisxGetStringValue()

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

◆ 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 FALSE, and Redis::pipeline.

◆ redisxIgnoreReplyAsync()

int redisxIgnoreReplyAsync ( RedisClient * cl )

Silently consumes a reply from the specified Redis channel.

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.

References REDIS_NULL, redisxDestroyRESP(), redisxReadReplyAsync(), x_error(), X_NULL, 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"

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

References FALSE, Redis::id, Redis::interactive, Redis::pipeline, REDISX_CHANNELS, REDISX_INTERACTIVE_CHANNEL, REDISX_PIPELINE_CHANNEL, REDISX_SUBSCRIPTION_CHANNEL, REDISX_TCP_PORT, Redis::subscription, TRUE, x_error(), x_trace_null(), and xStringCopyOf().

◆ 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, and Redis::interactive.

◆ 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, X_SUCCESS, and x_trace().

◆ 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 X_FAILURE if pthread_mutex_lock() returned an error X_NULL if the client is NULL.

See also: redisxLockConnected(); redisxUnlockClient()

References x_error(), X_FAILURE, X_NULL, 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. X_FAILURE if pthread_mutex_lock() returned an error X_NULL if the client is NULL REDIS_INVALID_CHANNEL if the channel is not enabled/connected.

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_ERROR, redisxCheckRESP(), redisxDestroyRESP(), redisxLockConnected(), redisxMultiSetAsync(), redisxReadReplyAsync(), RESP_SIMPLE_STRING, RESP::value, x_error(), X_GROUP_INVALID, X_NULL, X_SIZE_INVALID, and X_SUCCESS.

◆ 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 RedisEntry::length, redisxSendArrayRequestAsync(), redisxSkipReplyAsync(), x_error(), X_FAILURE, X_GROUP_INVALID, X_NULL, X_SIZE_INVALID, 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, redisxCheckRESP(), redisxDestroyRESP(), redisxRequest(), RESP_BULK_STRING, RESP_SIMPLE_STRING, RESP::value, x_error(), X_NULL, 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, redisxLockConnected(), redisxPublishAsync(), redisxUnlockClient(), x_error(), X_NULL, 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, redisxSendArrayRequestAsync(), redisxSkipReplyAsync(), x_error(), X_NULL, and X_SUCCESS.

◆ redisxReadReplyAsync()

RESP * redisxReadReplyAsync ( RedisClient * cl )

Reads a response from Redis and returns it.

Parameters

cl	Pointer to a Redis channel

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.

References FALSE, RESP::n, REDIS_INCOMPLETE_TRANSFER, REDIS_SIMPLE_STRING_SIZE, REDIS_UNEXPECTED_RESP, redisxDestroyRESP(), redisxReadReplyAsync(), RESP_ARRAY, RESP_BULK_STRING, RESP_ERROR, RESP_INT, RESP_SIMPLE_STRING, RESP::type, RESP::value, x_error(), X_FAILURE, X_PARSE_ERROR, X_SUCCESS, x_trace_null(), 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_error(), X_NULL, and 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.

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

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

◆ redisxScanKeys()

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

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
[out]	status	integer in which to return the status, which is X_SUCCESS (0) if successful, or may an error value from redisxRequest(), or:

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

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

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

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

◆ redisxScanTable()

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

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
[out]	status	integer in which to return the status, which is X_SUCCESS (0) if successful, or may an error value from redisxRequest(), or:

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

Returns: A RedisEntry[] array or NULL.

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

References RedisEntry::key, RedisEntry::length, RESP::n, redisxArrayRequest(), redisxCheckRESP(), 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(), xdprintf, 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_error(), X_INCOMPLETE, X_NULL, X_SUCCESS, and x_trace().

◆ redisxSendArrayRequestAsync()

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

Send a Redis request with an arbitrary number of arguments.

Parameters

cl	Pointer to the Redis client.
args	The array of string arguments to send.
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 else X_NO_SERVICE if not connected to the client or if send() failed.

References FALSE, REDISX_CMDBUF_SIZE, TRUE, x_error(), X_NULL, and X_SUCCESS.

◆ 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.

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

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

◆ 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_NULL, X_SUCCESS, and xStringCopyOf().

◆ redisxSetPipelineConsumer()

int redisxSetPipelineConsumer	(	Redis *	redis,
		void()(RESP )	f
	)

Sets the function processing valid pipeline responses.

Parameters

redis	Pointer to a Redis instance.
f	T he 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_error(), X_NULL, and 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.

See also: redisxConnect();

References x_error(), X_NULL, 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_error(), X_NULL, and X_SUCCESS.

◆ redisxSetTcpBuf()

void redisxSetTcpBuf ( int size )

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

Parameters

size	(bytes) requested buffer size, or <= 0 to use default value

References xvprintf.

◆ redisxSetTransmitErrorHandler()

int redisxSetTransmitErrorHandler	(	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.

References x_error(), X_NULL, 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_NULL, 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 if the variable was succesfully set, or: X_NO_INIT X_NAME_INVALID X_NULL X_NO_SERVICE X_FAILURE

References Redis::interactive, redisxCheckRESP(), redisxDestroyRESP(), redisxLockConnected(), redisxReadReplyAsync(), 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 required 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 redisxCheckRESP(), redisxDestroyRESP(), redisxReadReplyAsync(), redisxSendRequestAsync(), redisxSkipReplyAsync(), RESP_INT, 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.

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.

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

◆ redisxStartBlockAsync()

int redisxStartBlockAsync ( RedisClient * cl )

Starts an atomic Redis transaction block, by sending MULTI on the specified client connection. 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.

See also: redisxExecBlockAsync(); redisxAbortBlockAsync()

References TRUE, x_error(), X_NULL, 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 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 X_FAILURE if pthread_mutex_lock() returned an error X_NULL if the client is NULL

See also: redisxLockClient(); redisxLockConnected()

References x_error(), X_FAILURE, X_NULL, 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 redisxLockConnected(), redisxSendRequestAsync(), redisxUnlockClient(), Redis::subscription, x_error(), X_NULL, and X_SUCCESS.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ REDISX_LISTENER_REL_PRIORITY

◆ REDISX_VERSION_STRING

Typedef Documentation

◆ RedisErrorHandler

◆ RedisSubscriberCall

Enumeration Type Documentation

◆ redisx_channel

Function Documentation

◆ redisxAbortBlockAsync()

◆ redisxAddConnectHook()

◆ redisxAddDisconnectHook()

◆ redisxAddSubscriber()

◆ redisxArrayRequest()

◆ redisxCheckDestroyRESP()

◆ redisxCheckRESP()

◆ redisxClearConnectHooks()

◆ redisxClearDisconnectHooks()

◆ redisxClearSubscribers()

◆ redisxConnect()

◆ redisxDebugTraffic()

◆ redisxDestroy()

◆ redisxDestroyEntries()

◆ redisxDestroyKeys()

◆ redisxDestroyRESP()

◆ redisxDisconnect()

◆ redisxEndSubscription()

◆ redisxError()

◆ redisxErrorDescription()

◆ redisxExecBlockAsync()

◆ redisxGetClient()

◆ redisxGetKeys()

◆ redisxGetLockedConnectedClient()

◆ redisxGetScanCount()

◆ redisxGetStringValue()

◆ redisxGetTable()

◆ redisxGetTime()

◆ redisxGetValue()

◆ redisxHasPipeline()

◆ redisxIgnoreReplyAsync()

◆ redisxInit()

◆ redisxIsConnected()

◆ redisxIsVerbose()

◆ redisxLoadScript()

◆ redisxLockClient()

◆ redisxLockConnected()

◆ redisxMultiSet()

◆ redisxMultiSetAsync()

◆ redisxNotify()

◆ redisxPing()

◆ redisxPublish()

◆ redisxPublishAsync()

◆ redisxReadReplyAsync()

◆ redisxReconnect()

◆ redisxRemoveConnectHook()

◆ redisxRemoveDisconnectHook()

◆ redisxRemoveSubscribers()

◆ redisxRequest()

◆ redisxScanKeys()

◆ redisxScanTable()

◆ redisxSelectDB()

◆ redisxSendArrayRequestAsync()

◆ redisxSendRequestAsync()

◆ redisxSetPassword()

◆ redisxSetPipelineConsumer()

◆ redisxSetPort()

◆ redisxSetScanCount()

◆ redisxSetTcpBuf()

◆ redisxSetTransmitErrorHandler()

◆ redisxSetUser()

◆ redisxSetValue()

◆ redisxSetValueAsync()

◆ redisxSetVerbose()

◆ redisxSkipReplyAsync()