Macros
#define	SCAN_INITIAL_STORE_CAPACITY 256
	Number of Redis keys to allocate initially when using SCAN to get list of keywords.

Functions
void	redisxDestroyEntries (RedisEntry *entries, int count)

void	redisxDestroyKeys (char **keys, int count)

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

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)

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

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)

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	redisxSetScanCount (Redis *redis, int count)

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)

Detailed Description

Date: Created on Aug 26, 2024

Author: Attila Kovacs

Table access functions for the RedisX library. These functions can be used both for Redis hash tables and for global key/value data in a Redis database.

Function Documentation

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

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

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

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

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

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

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

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

Macros

Functions

Detailed Description

Function Documentation

◆ redisxDestroyEntries()

◆ redisxDestroyKeys()

◆ redisxGetKeys()

◆ redisxGetScanCount()

◆ redisxGetStringValue()

◆ redisxGetTable()

◆ redisxGetValue()

◆ redisxMultiSet()

◆ redisxMultiSetAsync()

◆ redisxScanKeys()

◆ redisxScanTable()

◆ redisxSetScanCount()

◆ redisxSetValue()

◆ redisxSetValueAsync()