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

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

int	redisxClusterConnect (RedisCluster *cluster)

void	redisxClusterDestroy (RedisCluster *cluster)

int	redisxClusterDisconnect (RedisCluster *cluster)

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

Redis *	redisxClusterGetShard (RedisCluster cluster, const char key)

RedisCluster *	redisxClusterInit (Redis *node)

boolean	redisxClusterIsMigrating (const RESP *reply)

boolean	redisxClusterIsRedirected (const RESP *reply)

boolean	redisxClusterMoved (const RESP *reply)

Detailed Description

Date: Created on Jan 2, 2025

Author: Attila Kovacs

Function Documentation

◆ redisxClusterAskMigrating()

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

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

Parameters

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

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

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

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

◆ redisxClusterAskMigratingAsync()

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

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

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

Parameters

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

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

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

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

◆ redisxClusterConnect()

int redisxClusterConnect ( RedisCluster * cluster )

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

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

Parameters

cluster Pointer to a Redis cluster configuration

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

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

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

◆ redisxClusterDestroy()

void redisxClusterDestroy ( RedisCluster * cluster )

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

Parameters

cluster Pointer to a Redis cluster configuration.

See also: redisxClusterInit()

References RedisCluster::priv, and redisxClusterDisconnect().

◆ redisxClusterDisconnect()

int redisxClusterDisconnect ( RedisCluster * cluster )

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

Parameters

cluster Pointer to a Redis cluster configuration

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

See also: redisxClusterInit(); redisxClusterConnect()

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

◆ redisxClusterGetRedirection()

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

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

Parameters

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

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

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

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

◆ redisxClusterGetShard()

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

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

Parameters

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

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

See also: redisxClusterInit(); redisxClusterMoved()

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

◆ redisxClusterInit()

RedisCluster * redisxClusterInit ( Redis * node )

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

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

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

Parameters

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

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

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

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

◆ redisxClusterIsMigrating()

boolean redisxClusterIsMigrating ( const RESP * reply )

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

Parameters

reply The response obtained from the Redis shard / server.

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

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

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

◆ redisxClusterIsRedirected()

boolean redisxClusterIsRedirected ( const RESP * reply )

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

Parameters

reply The response obtained from the Redis shard / server.

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

See also: redisxClusterMoved(); redisxClusterIsMigrating()

References redisxClusterIsMigrating(), and redisxClusterMoved().

◆ redisxClusterMoved()

boolean redisxClusterMoved ( const RESP * reply )

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

Parameters

reply The response obtained from the Redis shard / server.

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

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

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

Functions

Detailed Description

Function Documentation

◆ redisxClusterAskMigrating()

◆ redisxClusterAskMigratingAsync()

◆ redisxClusterConnect()

◆ redisxClusterDestroy()

◆ redisxClusterDisconnect()

◆ redisxClusterGetRedirection()

◆ redisxClusterGetShard()

◆ redisxClusterInit()

◆ redisxClusterIsMigrating()

◆ redisxClusterIsRedirected()

◆ redisxClusterMoved()