This Readme reflects the latest changed in the master branch. See v1.0.0 for the Readme and documentation for the latest release (API/ABI history).
Hiredis is a minimalistic C client library for the Redis database.
It is minimalistic because it just adds minimal support for the protocol, but at the same time it uses a high level printf-alike API in order to make it much higher level than otherwise suggested by its minimal code base and the lack of explicit bindings for every Redis command.
Apart from supporting sending commands and receiving replies, it comes with a reply parser that is decoupled from the I/O layer. It is a stream parser designed for easy reusability, which can for instance be used in higher level language bindings for efficient reply parsing.
Hiredis only supports the binary-safe Redis protocol, so you can use it with any Redis version >= 1.2.0.
The library comes with multiple APIs. There is the synchronous API, the asynchronous API and the reply parsing API.
-
After v1.2.0 we modified how we invoke
poll(2)to wait for connections to complete, such that we will now retry the call if it is interrupted by a signal until:a) The connection succeeds or fails. b) The overall connection timeout is reached.
In previous versions, an interrupted
poll(2)call would cause the connection to fail withc->errset toREDIS_ERR_IOandc->errstrset topoll(2): Interrupted system call.
Almost all users will simply need to recompile their applications against the newer version of hiredis.
NOTE: Hiredis can now return nan in addition to -inf and inf in a REDIS_REPLY_DOUBLE.
Applications that deal with RESP3 doubles should make sure to account for this.
NOTE: v1.0.1 erroneously bumped SONAME, which is why it is skipped here.
Version 1.0.2 is simply 1.0.0 with a fix for CVE-2021-32765. They are otherwise identical.
Version 1.0.0 marks the first stable release of Hiredis.
It includes some minor breaking changes, mostly to make the exposed API more uniform and self-explanatory.
It also bundles the updated sds library, to sync up with upstream and Redis.
For code changes see the Changelog.
Note: As described below, a few member names have been changed but most applications should be able to upgrade with minor code changes and recompiling.
redisContexthas two additional members (free_privdata, andprivctx).redisOptions.timeouthas been renamed toredisOptions.connect_timeout, and we've addedredisOptions.command_timeout.redisReplyObjectFunctions.createArraynow takessize_tinstead ofintfor its length parameter.
Bulk and multi-bulk lengths less than -1 or greater than LLONG_MAX are now
protocol errors. This is consistent with the RESP specification. On 32-bit
platforms, the upper bound is lowered to SIZE_MAX.
Change redisReply.len to size_t, as it denotes the the size of a string
User code should compare this to size_t values as well. If it was used to
compare to other values, casting might be necessary or can be removed, if
casting was applied before.
Version 0.9.0 is a major overhaul of hiredis in every aspect. However, upgrading existing
code using hiredis should not be a big pain. The key thing to keep in mind when
upgrading is that hiredis >= 0.9.0 uses a redisContext* to keep state, in contrast to
the stateless 0.0.1 that only has a file descriptor to work with.
To consume the synchronous API, there are only a few function calls that need to be introduced:
redisContext *redisConnect(const char *ip, int port);
void *redisCommand(redisContext *c, const char *format, ...);
void freeReplyObject(void *reply);The function redisConnect is used to create a so-called redisContext. The
context is where Hiredis holds state for a connection. The redisContext
struct has an integer err field that is non-zero when the connection is in
an error state. The field errstr will contain a string with a description of
the error. More information on errors can be found in the Errors section.
After trying to connect to Redis using redisConnect you should
check the err field to see if establishing the connection was successful:
redisContext *c = redisConnect("127.0.0.1", 6379);
if (c == NULL || c->err) {
if (c) {
printf("Error: %s\n", c->errstr);
// handle error
} else {
printf("Can't allocate redis context\n");
}
}One can also use redisConnectWithOptions which takes a redisOptions argument
that can be configured with endpoint information as well as many different flags
to change how the redisContext will be configured.
redisOptions opt = {0};
/* One can set the endpoint with one of our helper macros */
if (tcp) {
REDIS_OPTIONS_SET_TCP(&opt, "localhost", 6379);
} else {
REDIS_OPTIONS_SET_UNIX(&opt, "/tmp/redis.sock");
}
/* And privdata can be specified with another helper */
REDIS_OPTIONS_SET_PRIVDATA(&opt, myPrivData, myPrivDataDtor);
/* Finally various options may be set via the `options` member, as described below */
opt->options |= REDIS_OPT_PREFER_IPV4;If a connection is lost, int redisReconnect(redisContext *c) can be used to restore the connection using the same endpoint and options as the given context.
There are several flags you may set in the redisOptions struct to change default behavior. You can specify the flags via the redisOptions->options member.
| Flag | Description |
|---|---|
| REDIS_OPT_NONBLOCK | Tells hiredis to make a non-blocking connection. |
| REDIS_OPT_REUSEADDR | Tells hiredis to set the SO_REUSEADDR socket option |
| REDIS_OPT_PREFER_IPV4 REDIS_OPT_PREFER_IPV6 REDIS_OPT_PREFER_IP_UNSPEC |
Informs hiredis to either prefer IPv4 or IPv6 when invoking getaddrinfo. REDIS_OPT_PREFER_IP_UNSPEC will cause hiredis to specify AF_UNSPEC in the getaddrinfo call, which means both IPv4 and IPv6 addresses will be searched simultaneously.Hiredis prefers IPv4 by default. |
| REDIS_OPT_NO_PUSH_AUTOFREE | Tells hiredis to not install the default RESP3 PUSH handler (which just intercepts and frees the replies). This is useful in situations where you want to process these messages in-band. |
| REDIS_OPT_NOAUTOFREEREPLIES | ASYNC: tells hiredis not to automatically invoke freeReplyObject after executing the reply callback. |
| REDIS_OPT_NOAUTOFREE | ASYNC: Tells hiredis not to automatically free the redisAsyncContext on connection/communication failure, but only if the user makes an explicit call to redisAsyncDisconnect or redisAsyncFree |
Note: A redisContext is not thread-safe.
The following socket options are applied directly to the underlying socket.
The values are not stored in the redisContext, so they are not automatically applied when reconnecting using redisReconnect().
These functions return REDIS_OK on success.
On failure, REDIS_ERR is returned and the underlying connection is closed.
To configure these for an asynchronous context (see Asynchronous API below), use ac->c to get the redisContext out of an asyncRedisContext.
int redisEnableKeepAlive(redisContext *c);
int redisEnableKeepAliveWithInterval(redisContext *c, int interval);Enables TCP keepalive by setting the following socket options (with some variations depending on OS):
SO_KEEPALIVE;TCP_KEEPALIVEorTCP_KEEPIDLE, value configurable using theintervalparameter, default 15 seconds;TCP_KEEPINTVLset to 1/3 ofinterval;TCP_KEEPCNTset to 3.
int redisSetTcpUserTimeout(redisContext *c, unsigned int timeout);Set the TCP_USER_TIMEOUT Linux-specific socket option which is as described in the tcp man page:
When the value is greater than 0, it specifies the maximum amount of time in milliseconds that trans mitted data may remain unacknowledged before TCP will forcibly close the corresponding connection and return ETIMEDOUT to the application. If the option value is specified as 0, TCP will use the system default.
There are several ways to issue commands to Redis. The first that will be introduced is
redisCommand. This function takes a format similar to printf. In the simplest form,
it is used like this:
reply = redisCommand(context, "SET foo bar");The specifier %s interpolates a string in the command, and uses strlen to
determine the length of the string:
reply = redisCommand(context, "SET foo %s", value);When you need to pass binary safe strings in a command, the %b specifier can be
used. Together with a pointer to the string, it requires a size_t length argument
of the string:
reply = redisCommand(context, "SET foo %b", value, (size_t) valuelen);Internally, Hiredis splits the command in different arguments and will convert it to the protocol used to communicate with Redis. One or more spaces separates arguments, so you can use the specifiers anywhere in an argument:
reply = redisCommand(context, "SET key:%s %s", myid, value);The return value of redisCommand holds a reply when the command was
successfully executed. When an error occurs, the return value is NULL and
the err field in the context will be set (see section on Errors).
Once an error is returned the context cannot be reused and you should set up
a new connection.
The standard replies that redisCommand are of the type redisReply. The
type field in the redisReply should be used to test what kind of reply
was received:
-
REDIS_REPLY_STATUS:- The command replied with a status reply. The status string can be accessed using
reply->str. The length of this string can be accessed usingreply->len.
- The command replied with a status reply. The status string can be accessed using
-
REDIS_REPLY_ERROR:- The command replied with an error. The error string can be accessed identical to
REDIS_REPLY_STATUS.
- The command replied with an error. The error string can be accessed identical to
-
REDIS_REPLY_INTEGER:- The command replied with an integer. The integer value can be accessed using the
reply->integerfield of typelong long.
- The command replied with an integer. The integer value can be accessed using the
-
REDIS_REPLY_NIL:- The command replied with a nil object. There is no data to access.
-
REDIS_REPLY_STRING:- A bulk (string) reply. The value of the reply can be accessed using
reply->str. The length of this string can be accessed usingreply->len.
- A bulk (string) reply. The value of the reply can be accessed using
-
REDIS_REPLY_ARRAY:- A multi bulk reply. The number of elements in the multi bulk reply is stored in
reply->elements. Every element in the multi bulk reply is aredisReplyobject as well and can be accessed viareply->element[..index..]. Redis may reply with nested arrays but this is fully supported.
- A multi bulk reply. The number of elements in the multi bulk reply is stored in
Hiredis also supports every new RESP3 data type which are as follows. For more information about the protocol see the RESP3 specification.
-
REDIS_REPLY_DOUBLE:- The command replied with a double-precision floating point number.
The value is stored as a string in the
strmember, and can be converted withstrtodor similar.
- The command replied with a double-precision floating point number.
The value is stored as a string in the
-
REDIS_REPLY_BOOL:- A boolean true/false reply.
The value is stored in the
integermember and will be either0or1.
- A boolean true/false reply.
The value is stored in the
-
REDIS_REPLY_MAP:- An array with the added invariant that there will always be an even number of elements.
The MAP is functionally equivalent to
REDIS_REPLY_ARRAYexcept for the previously mentioned invariant.
- An array with the added invariant that there will always be an even number of elements.
The MAP is functionally equivalent to
-
REDIS_REPLY_SET:- An array response where each entry is unique. Like the MAP type, the data is identical to an array response except there are no duplicate values.
-
REDIS_REPLY_PUSH:- An array that can be generated spontaneously by Redis.
This array response will always contain at least two subelements. The first contains the type of
PUSHmessage (e.g.message, orinvalidate), and the second being a sub-array with thePUSHpayload itself.
- An array that can be generated spontaneously by Redis.
This array response will always contain at least two subelements. The first contains the type of
-
REDIS_REPLY_ATTR:- An array structurally identical to a
MAPbut intended as meta-data about a reply. As of Redis 6.0.6 this reply type is not used in Redis
- An array structurally identical to a
-
REDIS_REPLY_BIGNUM:- A string representing an arbitrarily large signed or unsigned integer value.
The number will be encoded as a string in the
strmember ofredisReply.
- A string representing an arbitrarily large signed or unsigned integer value.
The number will be encoded as a string in the
-
REDIS_REPLY_VERB:- A verbatim string, intended to be presented to the user without modification.
The string payload is stored in the
strmember, and type data is stored in thevtypemember (e.g.txtfor raw text ormdfor markdown).
- A verbatim string, intended to be presented to the user without modification.
The string payload is stored in the
Replies should be freed using the freeReplyObject() function.
Note that this function will take care of freeing sub-reply objects
contained in arrays and nested arrays, so there is no need for the user to
free the sub replies (it is actually harmful and will corrupt the memory).
Important: the current version of hiredis (1.0.0) frees replies when the
asynchronous API is used. This means you should not call freeReplyObject when
you use this API. The reply is cleaned up by hiredis after the callback
returns. We may introduce a flag to make this configurable in future versions of the library.
To disconnect and free the context the following function can be used:
void redisFree(redisContext *c);This function immediately closes the socket and then frees the allocations done in creating the context.
Together with redisCommand, the function redisCommandArgv can be used to issue commands.
It has the following prototype:
void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);It takes the number of arguments argc, an array of strings argv and the lengths of the
arguments argvlen. For convenience, argvlen may be set to NULL and the function will
use strlen(3) on every argument to determine its length. Obviously, when any of the arguments
need to be binary safe, the entire array of lengths argvlen should be provided.
The return value has the same semantic as redisCommand.
To explain how Hiredis supports pipelining in a blocking connection, there needs to be understanding of the internal execution flow.
When any of the functions in the redisCommand family is called, Hiredis first formats the
command according to the Redis protocol. The formatted command is then put in the output buffer
of the context. This output buffer is dynamic, so it can hold any number of commands.
After the command is put in the output buffer, redisGetReply is called. This function has the
following two execution paths:
- The input buffer is non-empty:
- Try to parse a single reply from the input buffer and return it
- If no reply could be parsed, continue at 2
- The input buffer is empty:
- Write the entire output buffer to the socket
- Read from the socket until a single reply could be parsed
The function redisGetReply is exported as part of the Hiredis API and can be used when a reply
is expected on the socket. To pipeline commands, the only thing that needs to be done is
filling up the output buffer. For this cause, two commands can be used that are identical
to the redisCommand family, apart from not returning a reply:
void redisAppendCommand(redisContext *c, const char *format, ...);
void redisAppendCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);After calling either function one or more times, redisGetReply can be used to receive the
subsequent replies. The return value for this function is either REDIS_OK or REDIS_ERR, where
the latter means an error occurred while reading a reply. Just as with the other commands,
the err field in the context can be used to find out what the cause of this error is.
The following examples shows a simple pipeline (resulting in only a single call to write(2) and
a single call to read(2)):
redisReply *reply;
redisAppendCommand(context,"SET foo bar");
redisAppendCommand(context,"GET foo");
redisGetReply(context,(void**)&reply); // reply for SET
freeReplyObject(reply);
redisGetReply(context,(void**)&reply); // reply for GET
freeReplyObject(reply);This API can also be used to implement a blocking subscriber:
reply = redisCommand(context,"SUBSCRIBE foo");
freeReplyObject(reply);
while(redisGetReply(context,(void *)&reply) == REDIS_OK) {
// consume message
freeReplyObject(reply);
}When a function call is not successful, depending on the function either NULL or REDIS_ERR is
returned. The err field inside the context will be non-zero and set to one of the
following constants:
-
REDIS_ERR_IO: There was an I/O error while creating the connection, trying to write to the socket or read from the socket. If you includederrno.hin your application, you can use the globalerrnovariable to find out what is wrong. -
REDIS_ERR_EOF: The server closed the connection which resulted in an empty read. -
REDIS_ERR_PROTOCOL: There was an error while parsing the protocol. -
REDIS_ERR_OTHER: Any other error. Currently, it is only used when a specified hostname to connect to cannot be resolved.
In every case, the errstr field in the context will be set to hold a string representation
of the error.
Hiredis comes with an asynchronous API that works easily with any event library. Examples are bundled that show using Hiredis with libev and libevent.
The function redisAsyncConnect can be used to establish a non-blocking connection to
Redis. It returns a pointer to the newly created redisAsyncContext struct. The err field
should be checked after creation to see if there were errors creating the connection.
Because the connection that will be created is non-blocking, the kernel is not able to
instantly return if the specified host and port is able to accept a connection.
In case of error, it is the caller's responsibility to free the context using redisAsyncFree()
Note: A redisAsyncContext is not thread-safe.
An application function creating a connection might look like this:
void appConnect(myAppData *appData)
{
redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379);
if (c->err) {
printf("Error: %s\n", c->errstr);
// handle error
redisAsyncFree(c);
c = NULL;
} else {
appData->context = c;
appData->connecting = 1;
c->data = appData; /* store application pointer for the callbacks */
redisAsyncSetConnectCallback(c, appOnConnect);
redisAsyncSetDisconnectCallback(c, appOnDisconnect);
}
}The asynchronous context should hold a connect callback function that is called when the connection attempt completes, either successfully or with an error. It can also hold a disconnect callback function that is called when the connection is disconnected (either because of an error or per user request). Both callbacks should have the following prototype:
void(const redisAsyncContext *c, int status);On a connect, the status argument is set to REDIS_OK if the connection attempt succeeded. In this
case, the context is ready to accept commands. If it is called with REDIS_ERR then the
connection attempt failed. The err field in the context can be accessed to find out the cause of the error.
After a failed connection attempt, the context object is automatically freed by the library after calling
the connect callback. This may be a good point to create a new context and retry the connection.
On a disconnect, the status argument is set to REDIS_OK when disconnection was initiated by the
user, or REDIS_ERR when the disconnection was caused by an error. When it is REDIS_ERR, the err
field in the context can be accessed to find out the cause of the error.
The context object is always freed after the disconnect callback fired. When a reconnect is needed, the disconnect callback is a good point to do so.
Setting the connect or disconnect callbacks can only be done once per context. For subsequent calls the
api will return REDIS_ERR. The function to set the callbacks have the following prototype:
/* Alternatively you can use redisAsyncSetConnectCallbackNC which will be passed a non-const
redisAsyncContext* on invocation (e.g. allowing writes to the privdata member). */
int redisAsyncSetConnectCallback(redisAsyncContext *ac, redisConnectCallback *fn);
int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);ac->data may be used to pass user data to both callbacks. A typical implementation
might look something like this:
void appOnConnect(redisAsyncContext *c, int status)
{
myAppData *appData = (myAppData*)c->data; /* get my application specific context*/
appData->connecting = 0;
if (status == REDIS_OK) {
appData->connected = 1;
} else {
appData->connected = 0;
appData->err = c->err;
appData->context = NULL; /* avoid stale pointer when callback returns */
}
appAttemptReconnect();
}
void appOnDisconnect(redisAsyncContext *c, int status)
{
myAppData *appData = (myAppData*)c->data; /* get my application specific context*/
appData->connected = 0;
appData->err = c->err;
appData->context = NULL; /* avoid stale pointer when callback returns */
if (status == REDIS_OK) {
appNotifyDisconnectCompleted(mydata);
} else {
appNotifyUnexpectedDisconnect(mydata);
appAttemptReconnect();
}
}In an asynchronous context, commands are automatically pipelined due to the nature of an event loop. Therefore, unlike the synchronous API, there is only a single way to send commands. Because commands are sent to Redis asynchronously, issuing a command requires a callback function that is called when the reply is received. Reply callbacks should have the following prototype:
void(redisAsyncContext *c, void *reply, void *privdata);The privdata argument can be used to curry arbitrary data to the callback from the point where
the command is initially queued for execution.
The functions that can be used to issue commands in an asynchronous context are:
int redisAsyncCommand(
redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,
const char *format, ...);
int redisAsyncCommandArgv(
redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,
int argc, const char **argv, const size_t *argvlen);Both functions work like their blocking counterparts. The return value is REDIS_OK when the command
was successfully added to the output buffer and REDIS_ERR otherwise. Example: when the connection
is being disconnected per user-request, no new commands may be added to the output buffer and REDIS_ERR is
returned on calls to the redisAsyncCommand family.
If the reply for a command with a NULL callback is read, it is immediately freed. When the callback
for a command is non-NULL, the memory is freed immediately following the callback: the reply is only
valid for the duration of the callback.
All pending callbacks are called with a NULL reply when the context encountered an error.
For every command issued, with the exception of SUBSCRIBE and PSUBSCRIBE, the callback is
called exactly once. Even if the context object id disconnected or deleted, every pending callback
will be called with a NULL reply.
For SUBSCRIBE and PSUBSCRIBE, the callbacks may be called repeatedly until an unsubscribe
message arrives. This will be the last invocation of the callback. In case of error, the callbacks
may receive a final NULL reply instead.
An asynchronous connection can be terminated using:
void redisAsyncDisconnect(redisAsyncContext *ac);When this function is called, the connection is not immediately terminated. Instead, new
commands are no longer accepted and the connection is only terminated when all pending commands
have been written to the socket, their respective replies have been read and their respective
callbacks have been executed. After this, the disconnection callback is executed with the
REDIS_OK status and the context object is freed.
The connection can be forcefully disconnected using
void redisAsyncFree(redisAsyncContext *ac);In this case, nothing more is written to the socket, all pending callbacks are called with a NULL
reply and the disconnection callback is called with REDIS_OK, after which the context object
is freed.
There are a few hooks that need to be set on the context object after it is created.
See the adapters/ directory for bindings to libev and libevent.
Hiredis comes with a reply parsing API that makes it easy for writing higher level language bindings.
The reply parsing API consists of the following functions:
redisReader *redisReaderCreate(void);
void redisReaderFree(redisReader *reader);
int redisReaderFeed(redisReader *reader, const char *buf, size_t len);
int redisReaderGetReply(redisReader *reader, void **reply);The same set of functions are used internally by hiredis when creating a normal Redis context, the above API just exposes it to the user for a direct usage.
The function redisReaderCreate creates a redisReader structure that holds a
buffer with unparsed data and state for the protocol parser.
Incoming data -- most likely from a socket -- can be placed in the internal
buffer of the redisReader using redisReaderFeed. This function will make a
copy of the buffer pointed to by buf for len bytes. This data is parsed
when redisReaderGetReply is called. This function returns an integer status
and a reply object (as described above) via void **reply. The returned status
can be either REDIS_OK or REDIS_ERR, where the latter means something went
wrong (either a protocol error, or an out of memory error).
The parser limits the level of nesting for multi bulk payloads to 7. If the multi bulk nesting level is higher than this, the parser returns an error.
The function redisReaderGetReply creates redisReply and makes the function
argument reply point to the created redisReply variable. For instance, if
the response of type REDIS_REPLY_STATUS then the str field of redisReply
will hold the status as a vanilla C string. However, the functions that are
responsible for creating instances of the redisReply can be customized by
setting the fn field on the redisReader struct. This should be done
immediately after creating the redisReader.
For example, hiredis-rb uses customized reply object functions to create Ruby objects.
Both when using the Reader API directly or when using it indirectly via a normal Redis context, the redisReader structure uses a buffer in order to accumulate data from the server. Usually this buffer is destroyed when it is empty and is larger than 16 KiB in order to avoid wasting memory in unused buffers
However when working with very big payloads destroying the buffer may slow
down performances considerably, so it is possible to modify the max size of
an idle buffer changing the value of the maxbuf field of the reader structure
to the desired value. The special value of 0 means that there is no maximum
value for an idle buffer, so the buffer will never get freed.
For instance if you have a normal Redis context you can set the maximum idle buffer to zero (unlimited) just with:
context->reader->maxbuf = 0;This should be done only in order to maximize performances when working with
large payloads. The context should be set back to REDIS_READER_MAX_BUF again
as soon as possible in order to prevent allocation of useless memory.
By default the hiredis reply parser sets the maximum number of multi-bulk elements to 2^32 - 1 or 4,294,967,295 entries. If you need to process multi-bulk replies with more than this many elements you can set the value higher or to zero, meaning unlimited with:
context->reader->maxelements = 0;SSL/TLS support is not built by default and requires an explicit flag:
make USE_SSL=1
This requires OpenSSL development package (e.g. including header files to be available.
When enabled, SSL/TLS support is built into extra libhiredis_ssl.a and
libhiredis_ssl.so static/dynamic libraries. This leaves the original libraries
unaffected so no additional dependencies are introduced.
First, you'll need to make sure you include the SSL header file:
#include <hiredis/hiredis.h>
#include <hiredis/hiredis_ssl.h>You will also need to link against libhiredis_ssl, in addition to
libhiredis and add -lssl -lcrypto to satisfy its dependencies.
Hiredis implements SSL/TLS on top of its normal redisContext or
redisAsyncContext, so you will need to establish a connection first and then
initiate an SSL/TLS handshake.
Before Hiredis can negotiate an SSL/TLS connection, it is necessary to initialize OpenSSL and create a context. You can do that in two ways:
- Work directly with the OpenSSL API to initialize the library's global context
and create
SSL_CTX *andSSL *contexts. With anSSL *object you can callredisInitiateSSL(). - Work with a set of Hiredis-provided wrappers around OpenSSL, create a
redisSSLContextobject to hold configuration and useredisInitiateSSLWithContext()to initiate the SSL/TLS handshake.
/* An Hiredis SSL context. It holds SSL configuration and can be reused across
* many contexts.
*/
redisSSLContext *ssl_context;
/* An error variable to indicate what went wrong, if the context fails to
* initialize.
*/
redisSSLContextError ssl_error = REDIS_SSL_CTX_NONE;
/* Initialize global OpenSSL state.
*
* You should call this only once when your app initializes, and only if
* you don't explicitly or implicitly initialize OpenSSL it elsewhere.
*/
redisInitOpenSSL();
/* Create SSL context */
ssl_context = redisCreateSSLContext(
"cacertbundle.crt", /* File name of trusted CA/ca bundle file, optional */
"/path/to/certs", /* Path of trusted certificates, optional */
"client_cert.pem", /* File name of client certificate file, optional */
"client_key.pem", /* File name of client private key, optional */
"redis.mydomain.com", /* Server name to request (SNI), optional */
&ssl_error);
if(ssl_context == NULL || ssl_error != REDIS_SSL_CTX_NONE) {
/* Handle error and abort... */
/* e.g.
printf("SSL error: %s\n",
(ssl_error != REDIS_SSL_CTX_NONE) ?
redisSSLContextGetError(ssl_error) : "Unknown error");
// Abort
*/
}
/* Create Redis context and establish connection */
c = redisConnect("localhost", 6443);
if (c == NULL || c->err) {
/* Handle error and abort... */
}
/* Negotiate SSL/TLS */
if (redisInitiateSSLWithContext(c, ssl_context) != REDIS_OK) {
/* Handle error, in c->err / c->errstr */
}Redis 6.0 introduced PUSH replies with the reply-type >. These messages are generated spontaneously and can arrive at any time, so must be handled using callbacks.
Hiredis installs handlers on redisContext and redisAsyncContext by default, which will intercept and free any PUSH replies detected. This means existing code will work as-is after upgrading to Redis 6 and switching to RESP3.
The callback prototypes differ between redisContext and redisAsyncContext.
void my_push_handler(void *privdata, void *reply) {
/* Handle the reply */
/* Note: We need to free the reply in our custom handler for
blocking contexts. This lets us keep the reply if
we want. */
freeReplyObject(reply);
}void my_async_push_handler(redisAsyncContext *ac, void *reply) {
/* Handle the reply */
/* Note: Because async hiredis always frees replies, you should
not call freeReplyObject in an async push callback. */
}There are two ways to set your own PUSH handlers.
-
Set
push_cborasync_push_cbin theredisOptionsstruct and connect withredisConnectWithOptionsorredisAsyncConnectWithOptions.redisOptions = {0}; REDIS_OPTIONS_SET_TCP(&options, "127.0.0.1", 6379); options->push_cb = my_push_handler; redisContext *context = redisConnectWithOptions(&options);
-
Call
redisSetPushCallbackorredisAsyncSetPushCallbackon a connected context.redisContext *context = redisConnect("127.0.0.1", 6379); redisSetPushCallback(context, my_push_handler);
Note
redisSetPushCallbackandredisAsyncSetPushCallbackboth return any currently configured handler, making it easy to override and then return to the old value.
If you have a unique use-case where you don't want hiredis to automatically intercept and free PUSH replies, you will want to configure no handler at all. This can be done in two ways.
-
Set the
REDIS_OPT_NO_PUSH_AUTOFREEflag inredisOptionsand leave the callback function pointerNULL.redisOptions = {0}; REDIS_OPTIONS_SET_TCP(&options, "127.0.0.1", 6379); options->options |= REDIS_OPT_NO_PUSH_AUTOFREE; redisContext *context = redisConnectWithOptions(&options);
-
Call
redisSetPushCallbackwithNULLonce connected.redisContext *context = redisConnect("127.0.0.1", 6379); redisSetPushCallback(context, NULL);
Note: With no handler configured, calls to
redisCommandmay generate more than one reply, so this strategy is only applicable when there's some kind of blockingredisGetReply()loop (e.g.MONITORorSUBSCRIBEworkloads).
Hiredis uses a pass-thru structure of function pointers defined in alloc.h that contain the currently configured allocation and deallocation functions. By default they just point to libc (malloc, calloc, realloc, etc).
One can override the allocators like so:
hiredisAllocFuncs myfuncs = {
.mallocFn = my_malloc,
.callocFn = my_calloc,
.reallocFn = my_realloc,
.strdupFn = my_strdup,
.freeFn = my_free,
};
// Override allocators (function returns current allocators if needed)
hiredisAllocFuncs orig = hiredisSetAllocators(&myfuncs);To reset the allocators to their default libc function simply call:
hiredisResetAllocators();Salvatore Sanfilippo (antirez at gmail),
Pieter Noordhuis (pcnoordhuis at gmail)
Michael Grunder (michael dot grunder at gmail)
Hiredis is released under the BSD license.
![not-a-robot[bot] avatar](https://avatars.githubusercontent.com/in/1308?v=4 "not-a-robot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent