Redis学习笔记(十一)Hiredis

Redis拥有众多语言的客户端实现,比如C, C++, Java, Python等等,详见文末第一条参考链接。本文主要介绍一个C客户端——hiredis,它支持Redis所有命令集及Pipelining等特性,同时支持事件驱动编程。

1.HIREDIS介绍

Hiredis是Redis数据库的一个极其精简的C客户端库。除了支持发送命令和接收响应之外,Hiredis还提供了与I/O层解耦的响应解析器。

Hiredis库有多个API,包括同步API(synchronous API)、异步API(asynchronous API)以及响应解析API(reply parsing API)。

Hiredis只支持二进制安全的Redis协议,因此您可以将它与任何Redis版本>=1.2.0的版本一起使用。

2.同步API

同步API主要使用如下几个函数:

(1)连接

函数redisConnect()用来创建一个所谓的redisContext对象,redisContext是一个主要用来为连接保存上下文的数据结构。如下所示:

其中,若err非零,表示连接有错误;errstr是对一个错误的文字描述。所以,每次调用该函数进行连接操作之后,都应该检查err的状态:

注:redisContext不是线程安全的。

(2)发送命令

向Redis发送命令有多种方法。首先要介绍的是redisCommand()函数,该函数的使用形式与printf()函数颇有几分相似,其中最简单的形式是:

同样,这种形式你也应该不陌生:

当你需要传递二进制安全字符串时,需要使用%b说明符。同时,需要指定传递值的长度(size_t类型):

当然,这种形式你也不应该陌生:

(3)使用replies

redisCommand()函数的返回值是:成功返回一个redisReply对象;失败返回NULL,并将redisContext对象中的err字段设置为相应的值(后面介绍)。

需要注意的是:一旦redisCommand()函数返回错误,相应的redisContext对象将不能再使用,您必须从新建立一个连接。

redisCommand()函数的返回类型redisReply如下所示:

其中,type字段标识了收到的响应的类型:

1)REDIS_REPLY_STATUS:表示响应类型为一个状态值,reply->str表示状态的文字表示,reply->len表示状态字符串的长度;

2)REDIS_REPLY_ERROR:表示命令的响应有误,reply->str表示错误的文字表示,reply->表示字符串的长度;

3)REDIS_REPLY_INTEGER:表示响应的类型为一个整型值,使用reply->integer可以获得该整型值;

4)REDIS_REPLY_NIL:命令以nil响应,表示没有数据可以访问;

5)REDIS_REPLY_STRING:表示响应类型为字符串,使用reply->str可以获取具体的字符串值,reply->len获取字符串长度;

6)REDIS_REPLY_ARRAY:多批量响应。其中响应的个数存储在reply->elements中,并且每个响应都是一个redisReply类型,可以通过reply->elements[index]来访问。

记住,使用完replies对象之后,需要使用freeReplyObject()函数进行释放。并且,该函数会释放数组和嵌套数组中包含的子响应对象,因此不需要用户释放子响应。

需要注意的是:当前版本的hiredis(0.10.0)在使用异步API时,不用调用freeReplyObject()函数去释放,hiredis会自行释放相应资源。但是这一行为可能再未来的版本中做出改变,注意观察新版本的更新日志。

(4)断开连接

断开连接使用redisFree()函数,该函数会关闭socket连接并释放在创建连接时分配的资源:

(5)管道(Pipelining)

对于管道命令,我们需要使用下面两个函数将命令添加到缓冲区中:

这两个函数的返回值为空。所以,在调用一个或多个上述函数之后,我们需要使用redisGetReply()函数来获取类型为redisReply的响应值,函数如下:

该函数返回值:成功返回REDIS_OK;失败返回REDIS_ERR。一般使用方法如下所示:

同时,redisGetReply()函数还可以用于实现阻塞订阅:

(6)错误判断

当一个函数执行失败后,其返回值要么为NULL,要么为REDIS_ERR。并且redisContext对象中的err字段会被设置为以下非零值之一:

1)REDIS_ERR_IO:表示创建连接或读写套接字时发生I/O错误。如果应用程序中包含了errno.h头文件,那么你可以通过全局变量errno来获取更详细的信息;
2)REDIS_ERR_EOF:表示服务器关闭连接而导致读的数据为空;
3)REDIS_ERR_PROTOCOL:表示解析redis协议时出错;
4)REDIS_ERR_OTHER:其他错误。

针对每一种错误码,都可以通过redisContext对象中的errstr字段获取更详细的文字描述。

3.异步API

Hiredis还提供了异步API,通过这些API可以轻松地使用任何事件库,比如libevent等。具体接口可以参考文末的第二条参考链接,此处不再赘述。

4.示例

前一篇博文在对比使用Pipelining和不使用Pipelining的示例中,我们使用的就是hiredis库,详见:http://dulishu.top/redis-pipelining/

 

5.其他

本文主要是对hiredis库常用函数做了简单介绍,更多详细内容请参考文末的参考链接。

 

参考:
https://redis.io/clients#c
https://github.com/redis/hiredis

《Redis学习笔记(十一)Hiredis》有1个想法

发表评论

电子邮件地址不会被公开。 必填项已用*标注