Commit 3c888150 authored by antirez's avatar antirez
Browse files

More detailed doc for the async API.

parent f2ddeeae
...@@ -241,22 +241,32 @@ instantly return if the specified host and port is able to accept a connection. ...@@ -241,22 +241,32 @@ instantly return if the specified host and port is able to accept a connection.
// handle error // handle error
} }
The asynchronous context can hold a disconnect callback function that is called when the The asynchronous context can hold a connect callback and a disconnect callback function.
connection is disconnected (either because of an error or per user request). This function should The connect callback is called when the connection was successfully established, or when there was
have the following prototype: an error in the process of connecting. The disconnect callback is called when the connection was
disconnected (either because of an error or per user request). This functions should 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 connection the `status` argument is set to `REDIS_OK` when there are no connection errors.
user, or `REDIS_ERR` when the disconnection was caused by an error. When it is `REDIS_ERR`, the `err` When it is set to `REDIS_ERR` it signals that there was an error during the connection
field in the context can be accessed to find out the cause of the error. (the error can be accessed using the `err` field of the context).
The context object is always free'd after the disconnect callback fired. When a reconnect is needed, On a disconnection, the `status` argument is set to `REDIS_OK` when the disconnection was initiated
the disconnect callback is a good point to do so. 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.
Setting the disconnect callback can only be done once per context. For subsequent calls it will **Note**: On connection errors only the connect callback is called (with `REDIS_ERR` as status), while
return `REDIS_ERR`. The function to set the disconnect callback has the following prototype: the diconnect callback is not called because the context actually never established the connection.
The context object is always freed after the disconnect callback (or the connection callback
signaling an error) fired. When a reconnect is needed, the disconnect callback is a good point to do so.
Setting the connect or disconnect callback can only be done once per context. For subsequent calls it
will return `REDIS_ERR`. The functions to set the callbacks have the following prototypes:
int redisAsyncSetConnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);
int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn); int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);
### Sending commands and their callbacks ### Sending commands and their callbacks
...@@ -289,7 +299,9 @@ If the reply for a command with a `NULL` callback is read, it is immediately fre ...@@ -289,7 +299,9 @@ If the reply for a command with a `NULL` callback is read, it is immediately fre
for a command is non-`NULL`, the memory is free'd immediately following the callback: the reply is only for a command is non-`NULL`, the memory is free'd immediately following the callback: the reply is only
valid for the duration of the callback. valid for the duration of the callback.
All pending callbacks are called with a `NULL` reply when the context encountered an error. All pending callbacks are called with a `NULL` reply when the context encountered an error, so you can
assume that for every asynchronous command sent there is always a callback called (possibly with a NULL
reply object).
### Disconnecting ### Disconnecting
...@@ -303,6 +315,14 @@ have been written to the socket, their respective replies have been read and the ...@@ -303,6 +315,14 @@ have been written to the socket, their respective replies have been read and the
callbacks have been executed. After this, the disconnection callback is executed with the callbacks have been executed. After this, the disconnection callback is executed with the
`REDIS_OK` status and the context object is free'd. `REDIS_OK` status and the context object is free'd.
It is also possible to perform an *hard* disconnection that does not wait for pending commands
using the following function:
void redisAsyncFree(redisAsyncContext *ac);
This function immediately terminates the connection, calls all the pending callbacks, and
frees the context.
### Hooking it up to event library *X* ### Hooking it up to event library *X*
There are a few hooks that need to be set on the context object after it is created. There are a few hooks that need to be set on the context object after it is created.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment