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