A Redis client library that compiles on older and newer platforms alike, such as LynxOS 3.1.0 PowerPCs. It is quite full featured, supporting multiple Redis instances, pipelining, user-specified connect and disconnect hooks, multiple user-specified subscription listeners, and user-specified pipeline processors. More...

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

int	redisxCheckValid (const Redis *redis)

void	redisxDebugTraffic (boolean value)

int	redisxError (const char *func, int errorCode)

const char *	redisxErrorDescription (int code)

RESP *	redisxGetAttributes (Redis *redis)

RESP *	redisxGetHelloData (Redis *redis)

XLookupTable *	redisxGetInfo (Redis redis, const char parameter)

enum redisx_protocol	redisxGetProtocol (Redis *redis)

int	redisxGetTime (Redis redis, struct timespec t)

boolean	redisxHasPipeline (Redis *redis)

int	redisxIsGlobPattern (const char *str)

boolean	redisxIsVerbose ()

int	redisxPing (Redis redis, const char message)

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

int	redisxSelectDB (Redis *redis, int idx)

int	redisxSetPassword (Redis redis, const char passwd)

int	redisxSetPipelineConsumer (Redis *redis, RedisPipelineProcessor f)

int	redisxSetProtocol (Redis *redis, enum redisx_protocol protocol)

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

int	redisxSetSocketConfigurator (Redis *redis, RedisSocketConfigurator func)

int	redisxSetSocketErrorHandler (Redis *redis, RedisErrorHandler f)

int	redisxSetUser (Redis redis, const char username)

void	redisxSetVerbose (boolean value)

Detailed Description

A Redis client library that compiles on older and newer platforms alike, such as LynxOS 3.1.0 PowerPCs. It is quite full featured, supporting multiple Redis instances, pipelining, user-specified connect and disconnect hooks, multiple user-specified subscription listeners, and user-specified pipeline processors.

Date: May 4, 2018

Author: Attila Kovacs

Function Documentation

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

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 librarywas not initialized via initRedis. 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, redisxCheckValid(), redisxClearAttributesAsync(), redisxLockConnected(), redisxReadReplyAsync(), redisxSendArrayRequestAsync(), redisxUnlockClient(), x_error(), X_NULL, X_SUCCESS, and x_trace_null().

◆ 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, or else X_NO_INIT if the redis instance is not initialized.

References x_error(), X_NO_INIT, 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.

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

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

◆ 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: redisxGetHelloData()

References FALSE, redisxCheckDestroyRESP(), redisxDestroyRESP(), redisxRequest(), RESP_BULK_STRING, RESP::value, x_trace_null(), xCreateLookup(), xCreateStringField(), xCreateStruct(), xSetField(), and xStringCopyOf().

◆ 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 if the argument is NULL, or X_NO_INIT if the Redis server instance was not initialized.

See also: redisxSetProtocol()

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

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

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

◆ redisxIsVerbose()

boolean redisxIsVerbose ( )

Checks id verbose reporting is enabled.

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

References xIsVerbose().

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

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

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

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

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

◆ 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 if the redis argument in NULL, X_NO_INIT 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.

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

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

Functions

Detailed Description

Function Documentation

◆ redisxArrayRequest()

◆ redisxCheckValid()

◆ redisxDebugTraffic()

◆ redisxError()

◆ redisxErrorDescription()

◆ redisxGetAttributes()

◆ redisxGetHelloData()

◆ redisxGetInfo()

◆ redisxGetProtocol()

◆ redisxGetTime()

◆ redisxHasPipeline()

◆ redisxIsGlobPattern()

◆ redisxIsVerbose()

◆ redisxPing()

◆ redisxRequest()

◆ redisxSelectDB()

◆ redisxSetPassword()

◆ redisxSetPipelineConsumer()

◆ redisxSetProtocol()

◆ redisxSetPushProcessor()

◆ redisxSetSocketConfigurator()

◆ redisxSetSocketErrorHandler()

◆ redisxSetUser()

◆ redisxSetVerbose()