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