From cc7c35ce6091571b292c1daeb93ce91d1b809ee6 Mon Sep 17 00:00:00 2001 From: michael-grunder Date: Thu, 1 Sep 2022 15:50:19 -0700 Subject: Update documentation to explain redisConnectWithOptions. Additionally document the new `REDIS_OPT_PREFER_IPV4`, `REDIS_OPT_PREFER_IPV6` as well as the rest of our existing options. See #1096 --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index ff50d13..661325c 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ 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: + ```c redisContext *c = redisConnect("127.0.0.1", 6379); if (c == NULL || c->err) { @@ -94,6 +95,40 @@ if (c == NULL || c->err) { } ``` +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. + +```c +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; +``` + +### Configurable redisOptions flags + +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](https://man7.org/linux/man-pages/man7/socket.7.html) socket option | +| REDIS\_OPT\_PREFER\_IPV4
REDIS\_OPT\_PREFER_IPV6 | Informs hiredis to either prefer `IPV4` or `IPV6` when invoking [getaddrinfo](https://man7.org/linux/man-pages/man3/gai_strerror.3.html). Note that both of the options may be set at once, which will cause hiredis to spcify `AF_UNSPEC` in the getaddrinfo call, which means both `IPV4` and `IPV6` addresses will be searched simultaneously. | +| 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\_NOAUOTFREEREPLIES | **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.* ### Sending commands -- cgit v1.2.3