Version is now 2.5.1, first unstable release of Redis 2.6

[redis.git] / deps / hiredis / README.md

diff --git a/deps/hiredis/README.md b/deps/hiredis/README.md
index e39ff0c1bb3cf7e21c52cc4f2d5e485735336dda..a58101cc6e503bc4e14d44fc6b7e40408c641113 100644 (file)
--- a/deps/hiredis/README.md
+++ b/deps/hiredis/README.md
@@ -108,7 +108,7 @@ was received:
 * **`REDIS_REPLY_ARRAY`**:
     * A multi bulk reply. The number of elements in the multi bulk reply is stored in
       `reply->elements`. Every element in the multi bulk reply is a `redisReply` object as well
 * **`REDIS_REPLY_ARRAY`**:
     * A multi bulk reply. The number of elements in the multi bulk reply is stored in
       `reply->elements`. Every element in the multi bulk reply is a `redisReply` object as well

-      and can be accessed via `reply->elements[..index..]`.
+      and can be accessed via `reply->element[..index..]`.

       Redis may reply with nested arrays but this is fully supported.
 
 Replies should be freed using the `freeReplyObject()` function.
       Redis may reply with nested arrays but this is fully supported.
 
 Replies should be freed using the `freeReplyObject()` function.


@@ -116,6 +116,12 @@ Note that this function will take care of freeing sub-replies objects
 contained in arrays and nested arrays, so there is no need for the user to
 free the sub replies (it is actually harmful and will corrupt the memory).
 
 contained in arrays and nested arrays, so there is no need for the user to
 free the sub replies (it is actually harmful and will corrupt the memory).
 

+**Important:** the current version of hiredis (0.10.0) free's replies when the
+asynchronous API is used. This means you should not call `freeReplyObject` when
+you use this API. The reply is cleaned up by hiredis _after_ the callback
+returns. This behavior will probably change in future releases, so make sure to
+keep an eye on the changelog when upgrading (see issue #39).
+

 ### Cleaning up
 
 To disconnect and free the context the following function can be used:
 ### Cleaning up
 
 To disconnect and free the context the following function can be used:


@@ -171,7 +177,7 @@ the latter means an error occurred while reading a reply. Just as with the other
 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 `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

-a single call to `write(2)`):
+a single call to `read(2)`):

 
     redisReply *reply;
     redisAppendCommand(context,"SET foo bar");
 
     redisReply *reply;
     redisAppendCommand(context,"SET foo bar");


@@ -280,7 +286,8 @@ is being disconnected per user-request, no new commands may be added to the outp
 returned on calls to the `redisAsyncCommand` family.
 
 If the reply for a command with a `NULL` callback is read, it is immediately free'd. When the callback
 returned on calls to the `redisAsyncCommand` family.
 
 If the reply for a command with a `NULL` callback is read, it is immediately free'd. When the callback

-for a command is non-`NULL`, it is responsible for cleaning up the reply.
+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.

 
 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.
 


@@ -303,7 +310,41 @@ See the `adapters/` directory for bindings to *libev* and *libevent*.
 
 ## Reply parsing API
 
 
 ## Reply parsing API
 

-To be done.
+Hiredis comes with a reply parsing API that makes it easy for writing higher
+level language bindings.
+
+The reply parsing API consists of the following functions:
+
+    redisReader *redisReaderCreate(void);
+    void redisReaderFree(redisReader *reader);
+    int redisReaderFeed(redisReader *reader, const char *buf, size_t len);
+    int redisReaderGetReply(redisReader *reader, void **reply);
+
+### Usage
+
+The function `redisReaderCreate` creates a `redisReader` structure that holds a
+buffer with unparsed data and state for the protocol parser.
+
+Incoming data -- most likely from a socket -- can be placed in the internal
+buffer of the `redisReader` using `redisReaderFeed`. This function will make a
+copy of the buffer pointed to by `buf` for `len` bytes. This data is parsed
+when `redisReaderGetReply` is called. This function returns an integer status
+and a reply object (as described above) via `void **reply`. The returned status
+can be either `REDIS_OK` or `REDIS_ERR`, where the latter means something went
+wrong (either a protocol error, or an out of memory error).
+
+### Customizing replies
+
+The function `redisReaderGetReply` creates `redisReply` and makes the function
+argument `reply` point to the created `redisReply` variable. For instance, if
+the response of type `REDIS_REPLY_STATUS` then the `str` field of `redisReply`
+will hold the status as a vanilla C string. However, the functions that are
+responsible for creating instances of the `redisReply` can be customized by
+setting the `fn` field on the `redisReader` struct. This should be done
+immediately after creating the `redisReader`.
+
+For example, [hiredis-rb](https://github.com/pietern/hiredis-rb/blob/master/ext/hiredis_ext/reader.c)
+uses customized reply object functions to create Ruby objects.

 
 ## AUTHORS
 
 
 ## AUTHORS