zeekling/hiredis
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add section on errors to readme

Browse Source
This commit is contained in:
Pieter Noordhuis 2010-11-26 15:14:51 +01:00
parent 4eab917a24
commit e24023a46a
1 changed files with 37 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
README.md
View File

@ -39,7 +39,8 @@ The function `redisConnect` is used to create a so-called `redisContext`. The
context is where Hiredis holds state for a connection. The `redisContext` context is where Hiredis holds state for a connection. The `redisContext`
struct has an integer `err` field that is non-zero when an the connection is in struct has an integer `err` field that is non-zero when an the connection is in
an error state. The field `errstr` will contain a string with a description of an error state. The field `errstr` will contain a string with a description of
the error. After trying to connect to Redis using `redisConnect` you should 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: check the `err` field to see if establishing the connection was successful:
redisContext *c = redisConnect("127.0.0.1", 6379); redisContext *c = redisConnect("127.0.0.1", 6379);
@ -77,8 +78,8 @@ anywhere in an argument:
### Using replies ### Using replies
The return value of `redisCommand` holds a reply when the command was The return value of `redisCommand` holds a reply when the command was
successfully executed. When the return value is `NULL`, the `error` field successfully executed. When an error occurs, the return value is `NULL` and
in the context can be used to find out what was the cause of failure. 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 Once an error is returned the context cannot be reused and you should set up
a new connection. a new connection.
@ -167,7 +168,7 @@ to the `redisCommand` family, apart from not returning a reply:
After calling either function one or more times, `redisGetReply` can be used to receive the 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 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 latter means an error occurred while reading a reply. Just as with the other commands,
the `error` field in the context can be used to find out what the cause of this error is. 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 The following examples shows a simple pipeline (resulting in only a single call to `write(2)` and
a single call to `write(2)`): a single call to `write(2)`):
@ -185,10 +186,35 @@ This API can also be used to implement a blocking subscriber:
reply = redisCommand(context,"SUBSCRIBE foo"); reply = redisCommand(context,"SUBSCRIBE foo");
freeReplyObject(reply); freeReplyObject(reply);
while(redisGetReply(context,&reply) == REDIS_OK) { while(redisGetReply(context,&reply) == REDIS_OK) {
// consume message // consume message
freeReplyObject(reply); freeReplyObject(reply);
} }
### Errors
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 included `errno.h` in your
application, you can use the global `errno` variable 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.
## Asynchronous API ## Asynchronous API
Hiredis comes with an asynchronous API that works easily with any event library. Hiredis comes with an asynchronous API that works easily with any event library.
@ -198,15 +224,15 @@ and [libevent](http://monkey.org/~provos/libevent/).
### Connecting ### Connecting
The function `redisAsyncConnect` can be used to establish a non-blocking connection to 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 `error` field 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. 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 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. instantly return if the specified host and port is able to accept a connection.
redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379); redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379);
if (c->error != NULL) { if (c->err) {
printf("Error: %s\n", c->error); printf("Error: %s\n", c->errstr);
// handle error // handle error
} }
The asynchronous context can hold a disconnect callback function that is called when the The asynchronous context can hold a disconnect callback function that is called when the
@ -216,7 +242,7 @@ have the following prototype:
void(const redisAsyncContext *c, int status); void(const redisAsyncContext *c, int status);
On a disconnect, the `status` argument is set to `REDIS_OK` when disconnection was initiated by the 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 `error` 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. field in the context can be accessed to find out the cause of the error.
The context object is always free'd after the disconnect callback fired. When a reconnect is needed, The context object is always free'd after the disconnect callback fired. When a reconnect is needed,