PageRenderTime 42ms CodeModel.GetById 13ms app.highlight 25ms RepoModel.GetById 1ms app.codeStats 0ms

/hiredis/README.md

http://github.com/nicolasff/webdis
Markdown | 392 lines | 317 code | 75 blank | 0 comment | 0 complexity | f35f29cc5b46282fd4b5dd663ac8aaac MD5 | raw file
  1[![Build Status](https://travis-ci.org/redis/hiredis.png)](https://travis-ci.org/redis/hiredis)
  2
  3# HIREDIS
  4
  5Hiredis is a minimalistic C client library for the [Redis](http://redis.io/) database.
  6
  7It is minimalistic because it just adds minimal support for the protocol, but
  8at the same time it uses a high level printf-alike API in order to make it
  9much higher level than otherwise suggested by its minimal code base and the
 10lack of explicit bindings for every Redis command.
 11
 12Apart from supporting sending commands and receiving replies, it comes with
 13a reply parser that is decoupled from the I/O layer. It
 14is a stream parser designed for easy reusability, which can for instance be used
 15in higher level language bindings for efficient reply parsing.
 16
 17Hiredis only supports the binary-safe Redis protocol, so you can use it with any
 18Redis version >= 1.2.0.
 19
 20The library comes with multiple APIs. There is the
 21*synchronous API*, the *asynchronous API* and the *reply parsing API*.
 22
 23## UPGRADING
 24
 25Version 0.9.0 is a major overhaul of hiredis in every aspect. However, upgrading existing
 26code using hiredis should not be a big pain. The key thing to keep in mind when
 27upgrading is that hiredis >= 0.9.0 uses a `redisContext*` to keep state, in contrast to
 28the stateless 0.0.1 that only has a file descriptor to work with.
 29
 30## Synchronous API
 31
 32To consume the synchronous API, there are only a few function calls that need to be introduced:
 33
 34```c
 35redisContext *redisConnect(const char *ip, int port);
 36void *redisCommand(redisContext *c, const char *format, ...);
 37void freeReplyObject(void *reply);
 38```
 39
 40### Connecting
 41
 42The function `redisConnect` is used to create a so-called `redisContext`. The
 43context is where Hiredis holds state for a connection. The `redisContext`
 44struct has an integer `err` field that is non-zero when the connection is in
 45an error state. The field `errstr` will contain a string with a description of
 46the error. More information on errors can be found in the **Errors** section.
 47After trying to connect to Redis using `redisConnect` you should
 48check the `err` field to see if establishing the connection was successful:
 49```c
 50redisContext *c = redisConnect("127.0.0.1", 6379);
 51if (c != NULL && c->err) {
 52    printf("Error: %s\n", c->errstr);
 53    // handle error
 54}
 55```
 56
 57### Sending commands
 58
 59There are several ways to issue commands to Redis. The first that will be introduced is
 60`redisCommand`. This function takes a format similar to printf. In the simplest form,
 61it is used like this:
 62```c
 63reply = redisCommand(context, "SET foo bar");
 64```
 65
 66The specifier `%s` interpolates a string in the command, and uses `strlen` to
 67determine the length of the string:
 68```c
 69reply = redisCommand(context, "SET foo %s", value);
 70```
 71When you need to pass binary safe strings in a command, the `%b` specifier can be
 72used. Together with a pointer to the string, it requires a `size_t` length argument
 73of the string:
 74```c
 75reply = redisCommand(context, "SET foo %b", value, (size_t) valuelen);
 76```
 77Internally, Hiredis splits the command in different arguments and will
 78convert it to the protocol used to communicate with Redis.
 79One or more spaces separates arguments, so you can use the specifiers
 80anywhere in an argument:
 81```c
 82reply = redisCommand(context, "SET key:%s %s", myid, value);
 83```
 84
 85### Using replies
 86
 87The return value of `redisCommand` holds a reply when the command was
 88successfully executed. When an error occurs, the return value is `NULL` and
 89the `err` field in the context will be set (see section on **Errors**).
 90Once an error is returned the context cannot be reused and you should set up
 91a new connection.
 92
 93The standard replies that `redisCommand` are of the type `redisReply`. The
 94`type` field in the `redisReply` should be used to test what kind of reply
 95was received:
 96
 97* **`REDIS_REPLY_STATUS`**:
 98    * The command replied with a status reply. The status string can be accessed using `reply->str`.
 99      The length of this string can be accessed using `reply->len`.
100
101* **`REDIS_REPLY_ERROR`**:
102    *  The command replied with an error. The error string can be accessed identical to `REDIS_REPLY_STATUS`.
103
104* **`REDIS_REPLY_INTEGER`**:
105    * The command replied with an integer. The integer value can be accessed using the
106      `reply->integer` field of type `long long`.
107
108* **`REDIS_REPLY_NIL`**:
109    * The command replied with a **nil** object. There is no data to access.
110
111* **`REDIS_REPLY_STRING`**:
112    * A bulk (string) reply. The value of the reply can be accessed using `reply->str`.
113      The length of this string can be accessed using `reply->len`.
114
115* **`REDIS_REPLY_ARRAY`**:
116    * A multi bulk reply. The number of elements in the multi bulk reply is stored in
117      `reply->elements`. Every element in the multi bulk reply is a `redisReply` object as well
118      and can be accessed via `reply->element[..index..]`.
119      Redis may reply with nested arrays but this is fully supported.
120
121Replies should be freed using the `freeReplyObject()` function.
122Note that this function will take care of freeing sub-reply objects
123contained in arrays and nested arrays, so there is no need for the user to
124free the sub replies (it is actually harmful and will corrupt the memory).
125
126**Important:** the current version of hiredis (0.10.0) frees replies when the
127asynchronous API is used. This means you should not call `freeReplyObject` when
128you use this API. The reply is cleaned up by hiredis _after_ the callback
129returns. This behavior will probably change in future releases, so make sure to
130keep an eye on the changelog when upgrading (see issue #39).
131
132### Cleaning up
133
134To disconnect and free the context the following function can be used:
135```c
136void redisFree(redisContext *c);
137```
138This function immediately closes the socket and then frees the allocations done in
139creating the context.
140
141### Sending commands (cont'd)
142
143Together with `redisCommand`, the function `redisCommandArgv` can be used to issue commands.
144It has the following prototype:
145```c
146void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
147```
148It takes the number of arguments `argc`, an array of strings `argv` and the lengths of the
149arguments `argvlen`. For convenience, `argvlen` may be set to `NULL` and the function will
150use `strlen(3)` on every argument to determine its length. Obviously, when any of the arguments
151need to be binary safe, the entire array of lengths `argvlen` should be provided.
152
153The return value has the same semantic as `redisCommand`.
154
155### Pipelining
156
157To explain how Hiredis supports pipelining in a blocking connection, there needs to be
158understanding of the internal execution flow.
159
160When any of the functions in the `redisCommand` family is called, Hiredis first formats the
161command according to the Redis protocol. The formatted command is then put in the output buffer
162of the context. This output buffer is dynamic, so it can hold any number of commands.
163After the command is put in the output buffer, `redisGetReply` is called. This function has the
164following two execution paths:
165
1661. The input buffer is non-empty:
167    * Try to parse a single reply from the input buffer and return it
168    * If no reply could be parsed, continue at *2*
1692. The input buffer is empty:
170    * Write the **entire** output buffer to the socket
171    * Read from the socket until a single reply could be parsed
172
173The function `redisGetReply` is exported as part of the Hiredis API and can be used when a reply
174is expected on the socket. To pipeline commands, the only things that needs to be done is
175filling up the output buffer. For this cause, two commands can be used that are identical
176to the `redisCommand` family, apart from not returning a reply:
177```c
178void redisAppendCommand(redisContext *c, const char *format, ...);
179void redisAppendCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
180```
181After calling either function one or more times, `redisGetReply` can be used to receive the
182subsequent replies. The return value for this function is either `REDIS_OK` or `REDIS_ERR`, where
183the latter means an error occurred while reading a reply. Just as with the other commands,
184the `err` field in the context can be used to find out what the cause of this error is.
185
186The following examples shows a simple pipeline (resulting in only a single call to `write(2)` and
187a single call to `read(2)`):
188```c
189redisReply *reply;
190redisAppendCommand(context,"SET foo bar");
191redisAppendCommand(context,"GET foo");
192redisGetReply(context,&reply); // reply for SET
193freeReplyObject(reply);
194redisGetReply(context,&reply); // reply for GET
195freeReplyObject(reply);
196```
197This API can also be used to implement a blocking subscriber:
198```c
199reply = redisCommand(context,"SUBSCRIBE foo");
200freeReplyObject(reply);
201while(redisGetReply(context,&reply) == REDIS_OK) {
202    // consume message
203    freeReplyObject(reply);
204}
205```
206### Errors
207
208When a function call is not successful, depending on the function either `NULL` or `REDIS_ERR` is
209returned. The `err` field inside the context will be non-zero and set to one of the
210following constants:
211
212* **`REDIS_ERR_IO`**:
213    There was an I/O error while creating the connection, trying to write
214    to the socket or read from the socket. If you included `errno.h` in your
215    application, you can use the global `errno` variable to find out what is
216    wrong.
217
218* **`REDIS_ERR_EOF`**:
219    The server closed the connection which resulted in an empty read.
220
221* **`REDIS_ERR_PROTOCOL`**:
222    There was an error while parsing the protocol.
223
224* **`REDIS_ERR_OTHER`**:
225    Any other error. Currently, it is only used when a specified hostname to connect
226    to cannot be resolved.
227
228In every case, the `errstr` field in the context will be set to hold a string representation
229of the error.
230
231## Asynchronous API
232
233Hiredis comes with an asynchronous API that works easily with any event library.
234Examples are bundled that show using Hiredis with [libev](http://software.schmorp.de/pkg/libev.html)
235and [libevent](http://monkey.org/~provos/libevent/).
236
237### Connecting
238
239The function `redisAsyncConnect` can be used to establish a non-blocking connection to
240Redis. It returns a pointer to the newly created `redisAsyncContext` struct. The `err` field
241should be checked after creation to see if there were errors creating the connection.
242Because the connection that will be created is non-blocking, the kernel is not able to
243instantly return if the specified host and port is able to accept a connection.
244```c
245redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379);
246if (c->err) {
247    printf("Error: %s\n", c->errstr);
248    // handle error
249}
250```
251
252The asynchronous context can hold a disconnect callback function that is called when the
253connection is disconnected (either because of an error or per user request). This function should
254have the following prototype:
255```c
256void(const redisAsyncContext *c, int status);
257```
258On a disconnect, the `status` argument is set to `REDIS_OK` when disconnection was initiated by the
259user, or `REDIS_ERR` when the disconnection was caused by an error. When it is `REDIS_ERR`, the `err`
260field in the context can be accessed to find out the cause of the error.
261
262The context object is always freed after the disconnect callback fired. When a reconnect is needed,
263the disconnect callback is a good point to do so.
264
265Setting the disconnect callback can only be done once per context. For subsequent calls it will
266return `REDIS_ERR`. The function to set the disconnect callback has the following prototype:
267```c
268int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);
269```
270### Sending commands and their callbacks
271
272In an asynchronous context, commands are automatically pipelined due to the nature of an event loop.
273Therefore, unlike the synchronous API, there is only a single way to send commands.
274Because commands are sent to Redis asynchronously, issuing a command requires a callback function
275that is called when the reply is received. Reply callbacks should have the following prototype:
276```c
277void(redisAsyncContext *c, void *reply, void *privdata);
278```
279The `privdata` argument can be used to curry arbitrary data to the callback from the point where
280the command is initially queued for execution.
281
282The functions that can be used to issue commands in an asynchronous context are:
283```c
284int redisAsyncCommand(
285  redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,
286  const char *format, ...);
287int redisAsyncCommandArgv(
288  redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,
289  int argc, const char **argv, const size_t *argvlen);
290```
291Both functions work like their blocking counterparts. The return value is `REDIS_OK` when the command
292was successfully added to the output buffer and `REDIS_ERR` otherwise. Example: when the connection
293is being disconnected per user-request, no new commands may be added to the output buffer and `REDIS_ERR` is
294returned on calls to the `redisAsyncCommand` family.
295
296If the reply for a command with a `NULL` callback is read, it is immediately freed. When the callback
297for a command is non-`NULL`, the memory is freed immediately following the callback: the reply is only
298valid for the duration of the callback.
299
300All pending callbacks are called with a `NULL` reply when the context encountered an error.
301
302### Disconnecting
303
304An asynchronous connection can be terminated using:
305```c
306void redisAsyncDisconnect(redisAsyncContext *ac);
307```
308When this function is called, the connection is **not** immediately terminated. Instead, new
309commands are no longer accepted and the connection is only terminated when all pending commands
310have been written to the socket, their respective replies have been read and their respective
311callbacks have been executed. After this, the disconnection callback is executed with the
312`REDIS_OK` status and the context object is freed.
313
314### Hooking it up to event library *X*
315
316There are a few hooks that need to be set on the context object after it is created.
317See the `adapters/` directory for bindings to *libev* and *libevent*.
318
319## Reply parsing API
320
321Hiredis comes with a reply parsing API that makes it easy for writing higher
322level language bindings.
323
324The reply parsing API consists of the following functions:
325```c
326redisReader *redisReaderCreate(void);
327void redisReaderFree(redisReader *reader);
328int redisReaderFeed(redisReader *reader, const char *buf, size_t len);
329int redisReaderGetReply(redisReader *reader, void **reply);
330```
331The same set of functions are used internally by hiredis when creating a
332normal Redis context, the above API just exposes it to the user for a direct
333usage.
334
335### Usage
336
337The function `redisReaderCreate` creates a `redisReader` structure that holds a
338buffer with unparsed data and state for the protocol parser.
339
340Incoming data -- most likely from a socket -- can be placed in the internal
341buffer of the `redisReader` using `redisReaderFeed`. This function will make a
342copy of the buffer pointed to by `buf` for `len` bytes. This data is parsed
343when `redisReaderGetReply` is called. This function returns an integer status
344and a reply object (as described above) via `void **reply`. The returned status
345can be either `REDIS_OK` or `REDIS_ERR`, where the latter means something went
346wrong (either a protocol error, or an out of memory error).
347
348The parser limits the level of nesting for multi bulk payloads to 7. If the
349multi bulk nesting level is higher than this, the parser returns an error.
350
351### Customizing replies
352
353The function `redisReaderGetReply` creates `redisReply` and makes the function
354argument `reply` point to the created `redisReply` variable. For instance, if
355the response of type `REDIS_REPLY_STATUS` then the `str` field of `redisReply`
356will hold the status as a vanilla C string. However, the functions that are
357responsible for creating instances of the `redisReply` can be customized by
358setting the `fn` field on the `redisReader` struct. This should be done
359immediately after creating the `redisReader`.
360
361For example, [hiredis-rb](https://github.com/pietern/hiredis-rb/blob/master/ext/hiredis_ext/reader.c)
362uses customized reply object functions to create Ruby objects.
363
364### Reader max buffer
365
366Both when using the Reader API directly or when using it indirectly via a
367normal Redis context, the redisReader structure uses a buffer in order to
368accumulate data from the server.
369Usually this buffer is destroyed when it is empty and is larger than 16
370KiB in order to avoid wasting memory in unused buffers
371
372However when working with very big payloads destroying the buffer may slow
373down performances considerably, so it is possible to modify the max size of
374an idle buffer changing the value of the `maxbuf` field of the reader structure
375to the desired value. The special value of 0 means that there is no maximum
376value for an idle buffer, so the buffer will never get freed.
377
378For instance if you have a normal Redis context you can set the maximum idle
379buffer to zero (unlimited) just with:
380```c
381context->reader->maxbuf = 0;
382```
383This should be done only in order to maximize performances when working with
384large payloads. The context should be set back to `REDIS_READER_MAX_BUF` again
385as soon as possible in order to prevent allocation of useless memory.
386
387## AUTHORS
388
389Hiredis was written by Salvatore Sanfilippo (antirez at gmail) and
390Pieter Noordhuis (pcnoordhuis at gmail) and is released under the BSD license.  
391Hiredis is currently maintained by Matt Stancliff (matt at genges dot com) and
392Jan-Erik Rediger (janerik at fnordig dot com)