簡介
Hiredis是redis數據庫一個輕量的C語言客戶端庫。
之所以輕量是由於它只是簡單的提供了對redis操作語句支持的接口，並沒有實現具體的操作語句的功能。但正是由於這種設計使我們只要熟悉了通用的redis操作語句就可以很容易的使用該庫和redis數據庫進行交互。
除了支持發送命令和接收應答/應答數據，它提供了對應答數據的解析操作。而且這個基於I/O層的數據流解析操作設計考慮到了複用性，可以對應答數據進行通用的解析操作。
Hirides僅僅支持二進制安全的redis協議，所以你只能針對版本號大於等於1.2.0的redis服務端使用。
庫包含多種API，包括同步命令操作API、異步命令操作API和對應答數據進行解析的API。
升級
版本0.9.0是hiredis很多特性一次大的更新。但是對現有代碼進行升級應該不會造成大的問題。升級時，要記住的關鍵一點是大於等於0.9.0的版本是使用redisContext*來保持連接狀態，之前的版本只是使用了無狀態的文件描述符。
同步API
有幾個API需要介紹
redisContext *redisConnect(const char *ip, int port);
void *redisCommand(redisContext *c, const char *format, …);
void freeReplyObject(void *reply);
連接redis數據庫
函數 redisConnect 被用來創建一個 redisContext。這個 context 是hiredis持有的連接狀態。redisConnect 結構體有一個整型的 err 變量來標識連接錯誤碼，如果連接錯誤則爲非零值。變量 errstr 標識連接結果的文字描述。更多這方面的信息會在以下Errors章節說明。當你使用 redisConnect 來創建連接時應該檢查err變量來判斷是否連接正常建立。
redisContext *c = redisConnect(“127.0.0.1”, 6379);
if (c != NULL && c->err) {
printf(“Error: %s\n”, c->errstr); // handle error }
發送命令到redis
有多種方法可以發送命令到redis。
首先介紹的是redisCommand。此函數類似於printf的使用方式，如
reply = redisCommand(context, “SET foo bar”);
類似於printf的s%格式化方式，如
reply = redisCommand(context, “SET foo %s”, value);
當你需要發送二進制安全的命令可以採用%b的格式化方式，同時需要一個字符串指針和size_t類型的字符串長度參數,如下
reply = redisCommand(context, “SET foo %b”, value, (size_t) valuelen);
在API內部，Hiredis根據不同的參數分割命令轉化爲操作redis數據庫的標準命令，你可以格式化多個參數來構造redis的命令，如下
reply = redisCommand(context, “SET key:%s %s”, myid, value);
處理redis應答
當命令被成功執行後redisCommand會有相應的返回值。如果有錯誤發生，返回值爲NULL並且redisReply結構體中的err變量將會被設置成相應的值（請參照Errors章節）。一旦有錯誤發生context不能被重用並且你需要建立一個新的連接。
redisCommand執行後返回值類型爲redisReply。通過redisReply結構體中的type變量可以確定命令執行的情況。
- REDIS_REPLY_STATUS：
返回執行結果爲狀態的命令。比如set命令的返回值的類型是REDIS_REPLY_STATUS，然後只有當返回信息是”OK”時，才表示該命令執行成功。可以通過reply->str得到文字信息，通過reply->len得到信息長度。
- REDIS_REPLY_ERROR：
返回錯誤。錯誤信息可以通過reply->str得到文字信息，通過reply->len得到信息長度。
- REDIS_REPLY_INTEGER：
返回整型標識。可以通過reply->integer變量得到類型爲long long的值。
- REDIS_REPLY_NIL:
返回nil對象，說明不存在要訪問的數據。
- REDIS_REPLY_STRING:
返回字符串標識。可以通過reply->str得到具體值，通過reply->len得到信息長度。
- REDIS_REPLY_ARRAY:
返回數據集標識。數據集中元素的數目可以通過reply->elements獲得，每個元素是個redisReply對象，元素值可以通過reply->element[..index..].*形式獲得，用在獲取多個數據結果的操作。
執行完命令調用後應該通過freeReplyObject()釋放redisReply，對於嵌套對象（比如數組）要注意，並不需要嵌套進行釋放，這樣是有害的會造成內存破壞。
Important:hiredis當前版本 (0.10.0)當使用異步API時會自己釋放replies對象。這意味着你使用異步API時並不需要主動調用freeReplyObject 。relpy對象當回調返回時將會被自動釋放。但是這種行爲也許會在將來的版本中改變，所以升級時請密切關注升級日誌。
清理連接資源
斷開連接並且釋放context使用以下函數
void redisFree(redisContext *c);
此函數立馬關閉socket並且釋放創建context時分配的資源。
發送多個命令參數
和redisCommand函數相似，redisCommandArgv函數可以用於傳輸多個命令參數。函數原型爲
void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
類似於 lpush， del key1 key2…, zadd key score1 member1 score2 member2…這類命令， 其中 argc是傳遞參數的個數， argv主要用於傳遞的string的value, 而argvlen 是每個string的size。
此函數返回值與redisCommand相似。參考https://gist.github.com/dspezia/1455082
管線（Pipelining）
爲了搞清楚Hiredis在阻塞連接下的管線操作，需要理解其內部執行過程。
當任何類似於redisCommand的函數被調用，Hiredis首先將命令格式化爲redis支持的命令協議。被格式化後的命令被放入context的輸出緩衝區，這個緩衝區是動態的，所以它可以容納任意數量的命令。在命令進入輸出緩衝區後，redisGetReply 函數被調用。這個函數有以下兩種執行方式：
輸入緩衝區非空：
- 從輸入緩衝區中嘗試解析單獨的reply對象並且返回reply
- 如果沒有reply能被解析，執行步驟2
輸入緩衝區爲空：
- 將整個輸出緩衝區寫入socket
- 從socket中讀取數據直到有一個reply能被解析
Hiredis爲了有效利用socket還提供了redisGetReply的接口。對於管線命令，需要完成的唯一事情就是填充輸出緩衝區。有兩個函數被用於執行此操作，這兩個函數基本與redisCommand函數功能類似，但是他們不返回reply
void redisAppendCommand(redisContext *c, const char *format, …);
void redisAppendCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
當這兩個函數被一次或多次調用時，通過redisGetReply依次返回replies。redisGetReply的返回值要麼是REDISOK或是REDISERR，REDIS_ERR意味着獲得reply發生了錯誤，想要得到具體的錯誤原因可以通過err變量來獲取。
以下通過一個簡單例子說明管線的使用：
redisReply *reply;
redisAppendCommand(context,”SET foo bar”);
redisAppendCommand(context,”GET foo”);
redisGetReply(context,&reply); // reply for SET
freeReplyObject(reply);
redisGetReply(context,&reply); // reply for GET
freeReplyObject(reply);
redisGetReply這個API也可以被用來實現阻塞的訂閱模式
reply = redisCommand(context,"SUBSCRIBE foo");
freeReplyObject(reply);
while(redisGetReply(context,&reply) == REDIS_OK){freeReplyObject(reply);}Errors
如果某些函數（如redisConnect， redisCommand（調用不成功，函數返回值爲NULL或者REDIS_ERR，此時context結構體中的err成員爲非零值，可能爲以下幾種常量
REDIS_ERR_IO:當創建連接時（試着寫socket或者讀socket）發生的I/O錯誤。如果你在代碼中包含了errno.h頭文件，你便能得到準確的錯誤碼。
REDIS_ERR_EOF:redis服務端已經關閉了此連接。
REDIS_ERR_PROTOCOL:服務端解析協議時發生了錯誤。
REDIS_ERR_OTHER:其他錯誤。目前僅僅表示無法解析目標主機名的錯誤。
在錯誤情況下，可以通過context結構體中的errstr成員得到錯誤的確切描述。
異步API
Hiredis自帶的異步API很容易和一些基於事件的庫結合使用。比如和libev、ibevent的結合使用。
連接
函數redisAsyncConnect被用來和redis建立非阻塞連接。它返回redisAsyncContext的結構體，結構體的err成員用來檢查在創建連接的過程中是否發生了錯誤。因爲創建的是非阻塞的連接，內核並不能立馬返回一個連接指定主機的結果。
redisAsyncContext *c = redisAsyncConnect("127.0.0.1", 6379);
if (c->err) {printf("Error: %s\n", c->errstr);// handle error
}異步Context可設置一個響應斷開連接事件的回調函數，當連接斷開時會相應執行。回調函數的原型爲
void(const redisAsyncContext *c, int status);
在斷開連接的情況下，當連接是由用戶自己斷開的status參數爲REDISOK，如果出現了其他錯誤status參數爲REDISERR，當錯誤時通過err成員可以得到準確的錯誤碼。
當回調執行完畢後context對象會自己釋放資源。此事件的回調函數給你創建一個新連接提供了便利。
一個context對象僅能設置一次斷開連接的回調，如果再進行下一次設置將會返回REDIS_ERR。設置斷開連接回調函數的原型爲：
int redisAsyncSetDisconnectCallback(redisAsyncContext *ac, redisDisconnectCallback *fn);
發送操作命令並且響應回調事件
在異步的情況下，redis的操作指令將會被自動加入事件循環隊列。由於發送命令執行的過程是異步的，當命令執行完畢後將會調用相應的回調函數。回調函數的原型爲
void(redisAsyncContext *c, void *reply, void *privdata);
privdata參數是由調用者自己定義的數據類型。
以下是進行異步命令操作的函數：
int redisAsyncCommand(redisAsyncContext *ac, redisCallbackFn *fn, void *privdata,const char *format, …);
int redisAsyncCommandArgv( redisAsyncContext *ac, redisCallbackFn *fn, void *privdata, int argc, const char **argv, const size_t *argvlen);
命令的使用方式和上面所講的同步接口類似。執行成功返回REDIS_OK，否則返回REDIS_ERR。比如連接已經關閉的情況下再使用redisAsyncCommand向此連接執行命令就會返回REDIS_ERR。
回調執行完畢後如果reply不爲空，回調執行完畢後將自動對reply的資源進行回收。
當context發生錯誤時回調得到的reply將爲空。
斷開連接
一個異步的連接可以通過下面這個函數終止
void redisAsyncDisconnect(redisAsyncContext *ac);
當這個函數被調用時，連接並不會被立即關閉，而是等待所有這個連接的異步命令操作執行完畢，並且回調事件已經執行完畢後才關閉此連接，這時在響應關閉連接事件的回調函數中得到的狀態爲REDIS_OK，此連接的資源也將會被自動回收。
將其掛接到事件庫X
在context對象被創建後進行很少的幾步操作就可以進行掛接。參看目錄adapters/下是如何掛接到libev 和 libevent下的。
應答解析API
Hiredis自帶的答覆解析API ，可以很容易與更高層次的語言進行綁定。 TODO：