1. hiredis 功能库:为什么异步接入比同步多一层事件循环
第一次把 Redis 塞进 C 服务时,我用的是 hiredis 的同步接口,redisCommand 一行下去、一行回来,逻辑直白得像调本地函数。等到单进程要同时盯十几个 key、还要接一堆定时任务,同步接口就开始拖后腿——一次网络抖动就能把整个线程按住。hiredis 这个功能库真正值钱的地方在它的异步 API,但异步不是把 redisCommand 换成 redisAsyncCommand 就完事,你得多养一个事件循环,把连接、命令、回复全部变成回调。这篇写的就是用 libevent 适配器把 hiredis 0.13.1 接进事件循环的完整过程,包括那几个只有踩过一次才记得住的回调语义。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 编译与链接功能库:hiredis 0.13.1 的构建与最小骨架
动手前先把一件事定下来:hiredis 本体是纯 C 库,编译它不需要 Redis 服务端在场,异步适配器也只是薄薄一层头文件加几个挂接函数。真正容易出问题的是第二步——把库接进你自己的构建链路。我见过太多人卡在 undefined reference to redisAsyncConnect 上,回头一查发现是链接参数写反了,或者 adapters/libevent.h 根本没进 include 路径。
2.1 生成库文件:make 出来的两种形态与安装位置
hiredis 的构建非常朴素,源码目录里直接 make,产出静态库和动态库两份。常见做法是:
bash复制cd hiredis-0.13.1
make
# 默认 PREFIX 是 /usr/local,头文件落到 /usr/local/include/hiredis/
sudo make install PREFIX=/usr/local
装完你会在 /usr/local/lib 下看到 libhiredis.a 和 libhiredis.so,头文件目录是 /usr/local/include/hiredis,所以代码里写 #include <hiredis/hiredis.h> 而不是 <hiredis.h>。这个层级差别是第一个小坑:抄了别人代码里的 <hiredis.h>,编译器会直接告诉你找不到文件。
有一点必须提前知道:adapters/libevent.h、adapters/libev.h、adapters/ae.h 这几个适配文件通常不会跟着 make install 进系统头文件目录。它们是源码树里的附加头文件,常见做法是在编译命令里额外把源码根目录加进 include 路径。我一般不会去手工拷贝这几个头文件到 /usr/local/include,因为升级库版本时两边容易不一致,留源码目录引用反而干净。
2.2 构建链路:include 路径与 -lhiredis、-levent 的链接顺序
异步接入同时依赖两个库:hiredis 和事件库本身。以 libevent 为例,一条能跑通的编译命令长这样:
bash复制gcc async_demo.c -o async_demo \
-I/usr/local/include/hiredis \
-I./hiredis-0.13.1 \
-L/usr/local/lib \
-lhiredis -levent
逐项说明:-I/usr/local/include/hiredis 让 hiredis/hiredis.h、hiredis/async.h 可被解析;-I./hiredis-0.13.1 是为了让 hiredis/adapters/libevent.h 这个相对路径成立,因为适配器在源码目录的 adapters/ 子目录下,而代码里的引用写法是 hiredis/adapters/libevent.h;-L/usr/local/lib 告诉链接器去哪儿找库文件;-lhiredis -levent 的顺序遵循「被依赖的放后面」,如果 libevent 装在非标准路径,还得补一个 -L 指向它的库目录。
如果你的发行版里 libevent 是用包管理器装的,头文件可能在 /usr/include/event2/,这时不需要额外的 -I,但要注意 libevent.h 适配器内部引用的是 event2/event.h 这一套新头文件,老版本 libevent 的 event.h 路径对不上会编译失败。这类报错很好认:错误行落在 adapters/libevent.h 内部而不是你的代码里,那就是头文件版本问题,不是你的写法问题。
2.3 最小可运行骨架:先用同步 PING 打通链路
在写任何异步代码之前,我强烈建议先用同步接口确认库装对了、网络通了。这一步花五分钟,能省掉后面半小时的自我怀疑。
c复制#include <hiredis/hiredis.h>
#include <stdio.h>
int main(void) {
redisContext *ctx = redisConnect("127.0.0.1", 6379);
if (ctx == NULL || ctx->err) {
if (ctx) {
printf("connect error: %s\n", ctx->errstr);
redisFree(ctx);
} else {
printf("alloc context failed\n");
}
return 1;
}
redisReply *reply = (redisReply *)redisCommand(ctx, "PING");
if (reply == NULL) {
printf("command failed\n");
redisFree(ctx);
return 1;
}
printf("PING -> %s\n", reply->str); // 正常输出 PONG
freeReplyObject(reply); // 同步版必须自己释放
redisFree(ctx);
return 0;
}
这段代码里有两个细节值得记牢,因为它们在异步版里会完全反过来。第一,同步版的 redisCommand 是阻塞的,返回的 redisReply 归调用方所有,freeReplyObject 是必须动作;第二,连接的失败信息在 ctx->err 和 ctx->errstr 里,你可以当场判断。到了异步版,连接是否成功要等回调里的 status,reply 也不用你释放——第 3 章会把这两处展开。
如果这一步就报 connect error: Connection refused,别急着怀疑 hiredis,先确认 Redis 服务在 6379 上活着,redis-cli ping 能不能回 PONG。同步骨架跑不通,异步只会把问题藏得更深。
3. 从同步到异步:redisAsyncConnect 与回调签名的语义变化
同步到异步这一步,最大的认知落差不是代码写法,而是「谁负责什么」发生了变化。同步版里你是调用者,返回值、错误码、内存释放全在你手上;异步版里你把这些交给了事件循环和 hiredis,自己退化成回调的接收方。理解不清楚这个角色转换,后面所有崩溃和丢命令都能从这儿找到根。
3.1 redisAsyncConnect 的返回值不看 err,看回调 status
同步版 redisConnect 失败时你把 ctx->err 一读就知道结果。异步版 redisAsyncConnect 返回的也是一个 redisAsyncContext *,但它代表的是「发起连接」这个动作,不是「连接已建立」这个事实。常见做法是:返回值只判空,连接结果等 redisAsyncSetConnectCallback 注册的回调。
c复制redisAsyncContext *actx = redisAsyncConnect("127.0.0.1", 6379);
if (actx == NULL || actx->err) {
// 这里是「连都发不出去」的级别,比如地址解析失败
printf("async connect init failed: %s\n", actx ? actx->errstr : "null ctx");
return;
}
注意 actx->err 在异步版里只能抓初始化阶段的错误,网络握手、服务端拒绝这些都得靠回调。很多人在这里判断完 err == 0 就以为连上了,转头在事件循环里发命令,结果命令悄悄消失——因为它压根没进到连接成功的状态。
3.2 三种回调的签名与注册顺序
异步接入一共要注册三类回调,顺序不能乱:
c复制void on_connect(const redisAsyncContext *actx, int status);
void on_disconnect(const redisAsyncContext *actx, int status);
void on_pong(redisAsyncContext *actx, void *reply, void *privdata);
on_connect 和 on_disconnect 的签名是 const redisAsyncContext * 加一个 int status,REDIS_OK 表示成功。redisAsyncCommand 的回调则是三个参数,第三个 privdata 是你在发命令时传进去的私有指针,用来区分不同命令的上下文——这一点在多命令并发时非常关键,否则你只能靠 reply 内容猜是哪条命令回来了。
注册顺序上,我的一般习惯是:先 redisAsyncSetConnectCallback,再 redisAsyncSetDisconnectCallback,最后才是把上下文挂到事件循环上。挂接之前把回调都设好,可以避免连接瞬间建立、回调却还没注册的竞态。虽然实际发生概率不高,但这个顺序不花任何代价。
3.3 reply 的内存归属:异步版不能 freeReplyObject
这是异步接入里最容易翻车的一处。同步版的 freeReplyObject(reply) 是肌肉记忆,写到异步回调里就变成堆损坏。
c复制void on_pong(redisAsyncContext *actx, void *reply, void *privdata) {
redisReply *r = (redisReply *)reply;
if (r == NULL) {
// 连接断开时,等待中的命令回调会拿到 NULL
return;
}
if (r->type == REDIS_REPLY_STRING) {
printf("reply: %s\n", r->str);
}
// 不要调用 freeReplyObject(r);
}
原因很直接:异步模式下 reply 的生命周期由 hiredis 管理,回调返回之后它会自己释放。你再去 freeReplyObject 一次,就是标准的 double free,症状可能是立刻崩溃,也可能是跑一段时间后堆结构被踩坏、在完全无关的地方挂掉——这种延迟爆发的崩溃最难查,所以这条规矩要刻进本能。
配合 3.2 提到的 NULL 容忍:当主流程调用 redisAsyncDisconnect 时,hiredis 会把正在等待回复的命令全部标记为放弃,这些命令的回调仍然会被调用,但 reply 参数是 NULL。如果你的回调第一行就 r->type,那就等着收段错误。判空必须是回调的第一句,不是可选项。
4. libevent 适配器接入实战:redisLibeventAttach 与事件循环
回调语义理清之后,剩下的就是把 hiredis 的异步上下文挂到事件循环上。hiredis 自己不带事件循环,它只提供几个适配文件把「可读事件」「可写事件」翻译成对应事件库的注册调用。libevent 是其中用得最多的一种,接入代码短,但初始化顺序和生命周期有几个必须说清的点。
4.1 适配文件怎么选:libevent、libev、ae
hiredis 自带三个适配器:adapters/libevent.h、adapters/libev.h、adapters/ae.h。选哪个不取决于性能,取决于你项目里已经在跑哪个事件循环——已经有 libevent 的地方硬插一个 libev,只会让你的进程里躺着两套 fd 监听机制。
判断标准很实际:项目里已经有 event_base 在用,就选 libevent;已经有 ev_loop,就选 libev;用了 Redis 作者那套 ae(比如从某些轻量服务里长出来的代码),就选 ae。三者对 hiredis 异步 API 的语义完全一致,只是挂接函数名不同,所以下面的接入流程换成 libev 也照样成立,只需要把 redisLibeventAttach 换成对应函数、把 event_base_dispatch 换成 ev_run。
4.2 接入代码与逐行说明
下面是完整的接入骨架,从事件循环创建到进入 dispatch:
c复制#include <hiredis/hiredis.h>
#include <hiredis/async.h>
#include <hiredis/adapters/libevent.h>
int main(void) {
struct event_base *base = event_base_new();
if (base == NULL) {
printf("event_base_new failed\n");
return 1;
}
redisAsyncContext *actx = redisAsyncConnect("127.0.0.1", 6379);
if (actx == NULL || actx->err) {
printf("async connect init failed\n");
event_base_free(base);
return 1;
}
redisLibeventAttach(actx, base); // 把上下文挂到事件循环
redisAsyncSetConnectCallback(actx, on_connect);
redisAsyncSetDisconnectCallback(actx, on_disconnect);
event_base_dispatch(base); // 进入事件循环,阻塞在这里
event_base_free(base);
return 0;
}
四个调用各自的职责:event_base_new 创建事件循环实例,整个进程通常只需要一个;redisAsyncConnect 发起非阻塞连接,此时连接还没建立;redisLibeventAttach 是关键一步,它把 hiredis 内部的读写事件注册到 base 上,没有这一句,后面的回调永远不会被触发;event_base_dispatch 进入循环,所有回调都在这个线程里执行。
常见的初始化顺序错误是把 redisLibeventAttach 放到 event_base_dispatch 之后,或者干脆忘了调用。症状很统一:程序不崩、不报错,就是什么回调都不来,你以为连上了,其实 hiredis 的 fd 没人监听。调试这类「静默无响应」时,第一件事就是确认 attach 在 dispatch 之前。
4.3 在 on_connect 里发第一条命令
连接成功的信号在 on_connect 里,发命令的动作也应该放在这里。这是最自然的位置,也最能暴露顺序问题:
c复制void on_connect(const redisAsyncContext *actx, int status) {
if (status != REDIS_OK) {
printf("connect failed: %s\n", actx->errstr);
return;
}
// 只有连接成功才发命令
redisAsyncCommand((redisAsyncContext *)actx, on_pong, NULL, "PING");
}
这里的 (redisAsyncContext *)actx 强制转换是必要的,因为 connect 回调把上下文声明成了 const,而 redisAsyncCommand 需要非 const 指针。这个转换本身没有风险,它只是签名约定上的不对称,不是让你去改上下文内容。
第三个参数传的是 privdata,这里给 NULL 是因为只有一条命令。一旦你开始并发发多条命令、需要区分回复归属,就应该传一个能标识业务的结构体指针,而不是继续用 NULL 然后靠 reply 内容猜。这个习惯在命令数量上去之后会救你很多次。
5. 异步功能库的避坑与排查:回调 NULL、内存释放与线程卡死
异步接入的坑有个共同特征:它们不报编译错误,运行时也不一定立刻崩,往往在压测或者跑了几小时之后才现形。下面五条是我在实际项目里踩过或者帮别人查过的,按「现象 → 原因 → 解决」写,遇到对应症状可以直接对号。
5.1 回调里做耗时操作,整个事件循环被按住
现象:并发量一上来,PING 的往返时间从毫秒级涨到几百毫秒,所有命令的回复都变慢,CPU 却不忙。
原因:异步回调运行在事件循环线程上。你在 on_pong 里做一个 200ms 的磁盘写入或者一次同步数据库查询,这 200ms 内事件循环无法处理任何其他 fd 事件,所有连接上的所有命令一起排队。卡住一秒就等于整个事件循环卡住一秒,这不是比喻,是字面意思。
解决:回调里只做「取数据、丢队列」这一件事,耗时逻辑交给工作线程。退一步的做法是延迟处理——先把 reply 里的内容拷贝出来,回调立刻返回,再用定时器或者下一轮事件回到事件循环发下一条命令。判断标准很简单:回调函数体里不允许出现任何可能阻塞超过一毫秒的调用,包括文件 IO、锁等待、同步网络请求。
5.2 回调里调用 freeReplyObject 导致堆损坏
现象:程序跑一段时间后随机崩溃,栈回溯落在 malloc/free 内部,跟你自己的业务代码看不出关系;或者表现为数据莫名其妙被改写。
原因:异步模式下 reply 由 hiredis 释放,你在回调里再释放一次就是 double free。它的可怕之处在于崩溃点跟肇事点经常不在一处,排查时容易被带偏到完全无关的模块。
解决:把「异步回调不释放 reply」当成硬规矩。如果团队里同步和异步代码混着写,建议在异步回调函数上方加一行注释明确写死,比记在脑子里可靠。另外注意 redisReply 内部可能还有嵌套的数组元素,同样归 hiredis 管,不要去动其中任何一个指针。
5.3 redisAsyncDisconnect 之后回调拿到 NULL
现象:主动断开连接时程序段错误,崩在回调的第一行,通常是读 reply->type 或者 reply->str。
原因:调用 redisAsyncDisconnect 后,正在等待回复的命令会被标记为放弃,这些命令的回调仍然会被调用一次,但 reply 参数是 NULL。这是 hiredis 的既定行为,不是异常。
解决:所有 redisAsyncCommand 的回调第一句统一判空,拿到 NULL 就直接返回,把这次命令当作失败处理。如果你的业务需要区分「连接断开导致的失败」和「命令本身返回错误」,可以在 privdata 里带一个状态标记,回调判空后置位,由上层统一收敛。
5.4 连接失败后仍然发命令
现象:日志里能看到 connect failed,但后续业务逻辑照常跑,命令全部石沉大海,没有任何回调被触发。
原因:命令是在 on_connect 的失败分支之外发出的,或者干脆在 main 里 redisAsyncConnect 之后立刻发。此时上下文还没进入已连接状态,hiredis 要么返回错误码,要么把命令挂起后随连接失败一起丢弃,无论哪种,业务侧都收不到回复。
解决:把发命令的动作严格约束在 on_connect 的 status == REDIS_OK 分支内。需要「连接恢复后自动重发」的场景,不要在原回调里递归重连,而是把待发命令放进自己的队列,等下一次 connect 成功回调里统一冲刷。
5.5 undefined reference to redisLibeventAttach
现象:编译链接阶段报符号未定义,明明头文件已经 include 进来了。
原因:两种情况最常见。一是链接参数里漏了 -levent,redisLibeventAttach 的实现需要 libevent 的符号;二是 -lhiredis 和 -levent 的顺序写反,或者库路径 -L 没指到实际安装位置。
解决:按 2.2 节的顺序排列链接参数,被依赖的库放右边。还有一种隐蔽情况是系统里装了两份 hiredis(比如包管理器一份、自己编译一份),头文件来自 A、库来自 B,版本不匹配时也可能报这个错。用 ldd 看最终链接到的 .so 路径,能快速确认是不是这个原因。
6. 进阶用法:把耗时逻辑挪出事件循环并验证回调时序
异步接入跑通之后,真正决定这套代码能不能上生产的,是「事件循环线程上到底跑了什么」。我的做法是给所有耗时逻辑划一条硬边界:回调只负责拷贝数据,业务处理全部移到工作线程,处理完再通过一次事件循环注册把结果送回。
具体落地时,可以用 event_base_once 把「下一轮要发的命令」延迟注册回事件循环,避免在工作线程里直接碰 hiredis 的上下文:
c复制// 回调里只做拷贝,不碰业务逻辑
void on_pong(redisAsyncContext *actx, void *reply, void *privdata) {
redisReply *r = (redisReply *)reply;
if (r == NULL) return;
char *copy = strdup(r->str); // 拷贝出来,回调立刻返回
enqueue_to_worker(copy, privdata); // 丢给工作线程
}
参数说明:strdup 出来的副本归工作线程所有,用完由工作线程释放;privdata 里放业务上下文,工作线程处理完之后如果需要发下一条命令,不要直接调用 redisAsyncCommand,而是把「发命令」这个动作包装成一个回调,通过事件循环注入回去。这样 hiredis 的上下文永远只被事件循环线程触碰,省掉一整类竞态问题。
验证时序的方法很土但有效:在 on_connect、on_pong、on_disconnect 三处各打一行带毫秒时间戳的日志,跑一轮 PING,看三条日志的先后和间隔。正常情况下 on_connect 在前,on_pong 紧随其后,间隔应该是亚毫秒到个位数毫秒。如果 on_pong 的时间和 on_connect 差了上百毫秒,说明你在连接回调里做了不该做的事;如果断开时先看到 on_disconnect 再看到一堆 on_pong 的 NULL 回调,那是正常的放弃序列,回调判空逻辑要能接住。
我现在每次接一个新的异步功能库,都会先用这套「三日志 + 判空 + 不释放 reply」的最小流程跑通,再往里塞业务。从那以后我每次改回调函数,都会强制走一遍这个验证:先确认回调里没有阻塞调用,再确认判空在第一行,最后确认没有多释放一次。希望帮到你。
