libcurl 通知机制详解：curl_multi_notify_enable 启用多句柄事件通知

libcurl 通知机制详解：curl_multi_notify_enable 启用多句柄事件通知

【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl

curl_multi_notify_enable是 libcurl 在 8.17.0 版本引入的 multi 接口扩展，用于按需开启 multi handle 上的事件通知类型，配合CURLMOPT_NOTIFYFUNCTION回调，让应用程序在传输状态发生变化时获得主动推送，而不是反复轮询查询状态。本文基于当前仓库的官方文档 curl_multi_notify_enable.md，结合 multi.c、multi_ntfy.c 与 multi.h 的源码实现，完整讲解该函数的原型、通知类型、调用语义、底层实现原理与实战注意事项，帮助读者在基于 libcurl 的多连接并发编程中正确使用这一事件驱动能力。

函数概览：一次调用，开启一类通知

curl_multi_notify_enable的函数原型定义在 include/curl/multi.h，其声明如下：

#include <curl/curl.h> CURLMcode curl_multi_notify_enable(CURLM *multi_handle, unsigned int notification);

函数接受两个参数：

• multi_handle：调用curl_multi_init()创建的多句柄；
• notification：要开启的通知类型，取值为CURLMNOTIFY_INFO_READ或CURLMNOTIFY_EASY_DONE之一。

函数的作用是在指定的 multi handle 上启用某一种通知类型的收集。当该类型的事件发生时，通过CURLMOPT_NOTIFYFUNCTION安装的回调函数会被调用，把事件推送给应用程序。

适用性说明：该函数不限定具体协议，对所有 libcurl 支持的协议（HTTP、FTP、SMTP、MQTT、WebSocket 等）均适用，官方文档的 Protocol 字段标记为 "All"。函数自 libcurl 8.17.0 起加入（文档头部元信息Added-in: 8.17.0）。

使用前提：回调与启用二者缺一不可

文档明确强调了一个关键约束：只有当通知回调已安装（通过CURLMOPT_NOTIFYFUNCTION设置）并且通知类型被启用时，事件才会被收集并分发给回调。也就是说，以下两个条件必须同时满足：

1. 通过curl_multi_setopt(multi, CURLMOPT_NOTIFYFUNCTION, callback)安装回调；
2. 通过curl_multi_notify_enable()启用至少一种通知类型。

回调的原型定义同样位于 include/curl/multi.h：

typedef void (*curl_notify_callback)(CURLM *m, unsigned int notification, CURL *easy, void *user_data);

四个参数的含义分别是：

• m：触发通知的 multi handle；
• notification：通知类型（即被启用的事件类型）；
• easy：与事件相关的 easy handle；
• user_data：通过CURLMOPT_NOTIFYDATA设置的私有数据指针。

配套的选项文档 CURLMOPT_NOTIFYFUNCTION.md 指出，默认情况下CURLMOPT_NOTIFYFUNCTION的取值为NULL（即未安装回调）。需要同步关注的是 CURLMOPT_NOTIFYDATA.md，用于给回调传递自定义上下文。

通知类型一览

当前仓库中定义了两种通知类型（见 include/curl/multi.h），未来可能还会新增：

CURLMNOTIFY_INFO_READ：有消息可读

启用该类型后，每当 multi handle 向空消息栈添加新消息时，会通知应用程序去调用curl_multi_info_read()处理这些消息。这里有一个值得注意的语义细节：通知只在消息被加入空栈时触发一次，之后继续追加消息不会重复触发。因此回调应一次性读取并清空消息栈，这样下一次有新消息加入空栈时才会再次收到通知。

该通知传入的easy参数是一个内部句柄（internal handle），并非应用程序直接创建的 easy handle。

CURLMNOTIFY_EASY_DONE：传输完成

启用该类型后，任意 easy handle 结束传输（无论成功还是失败）都会触发通知。回调中传入的easy参数指向结束传输的 easy handle——既可能是应用程序自己添加的句柄，也可能在使用 DoH 或其他特性时是 libcurl 内部的句柄，因此回调中不应假设它一定来自应用层。

调用语义与行为细节

官方文档给出了三点明确的调用语义：

• 支持多类型并存：可以同时启用多种通知类型，互不影响；
• 重复启用无害：对已经启用的类型再次调用curl_multi_notify_enable不是错误，幂等返回CURLM_OK；
• 可随时关闭：通过配套函数curl_multi_notify_disable可以关闭某个通知类型，接口声明见 curl_multi_notify_disable.md 与 include/curl/multi.h。

完整示例代码

官方文档提供了一个最小化示例，展示如何在创建 multi handle 后立即启用通知：

#include <curl/curl.h> int main(void) { int rc; CURLM *multi = curl_multi_init(); rc = curl_multi_notify_enable(multi, CURLMNOTIFY_INFO_READ); /* 检查 rc，非 CURLM_OK 表示出错 */ return 0; }

结合 CURLMOPT_NOTIFYFUNCTION.md 中的示例，一个更完整、可实际运行的用法是将回调安装、数据绑定与通知启用串联起来：

#include <stdio.h> #include <curl/curl.h> struct priv { void *ours; }; static void notify_cb(CURLM *multi, unsigned int notification, CURL *easy, void *notifyp) { struct priv *p = notifyp; (void)multi; (void)easy; printf("notification %u, my ptr: %p\n", notification, p->ours); /* 根据 notification 的值区分 CURLMNOTIFY_INFO_READ / CURLMNOTIFY_EASY_DONE， 分别调用 curl_multi_info_read() 或处理传输结束后的清理工作 */ } int main(void) { struct priv setup; CURLM *multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_NOTIFYFUNCTION, notify_cb); curl_multi_setopt(multi, CURLMOPT_NOTIFYDATA, &setup); curl_multi_notify_enable(multi, CURLMNOTIFY_INFO_READ); curl_multi_notify_enable(multi, CURLMNOTIFY_EASY_DONE); /* ... 添加 easy handle、调用 curl_multi_perform 等驱动循环 ... */ return 0; }

返回值与错误处理

函数返回CURLMcode枚举值。CURLM_OK（值为 0）表示一切正常，非零值表示发生了错误，具体错误码参见 libcurl-errors(3) 文档。

完整的CURLMcode枚举定义在 include/curl/multi.h，与本函数相关的错误码包括：

• CURLM_OK：成功；
• CURLM_BAD_HANDLE：传入的 multi handle 无效；
• CURLM_OUT_OF_MEMORY：内存分配失败；
• CURLM_UNKNOWN_OPTION：传入的通知类型不被支持（结合实现看，即类型值超出当前已知范围）；
• CURLM_BAD_FUNCTION_ARGUMENT：函数被以错误的参数调用。

官方文档特别提醒：返回码是针对整个 multi 栈（whole multi stack）的。即使这些函数返回了 OK，个别传输仍可能发生了问题，需要在回调或curl_multi_info_read()中进一步核对每个 easy handle 的结果。

源码实现解析：从 API 入口到事件分发的完整链路

要真正理解curl_multi_notify_enable，需要沿着仓库源码追踪它的实现链路。

API 入口：线程安全的守卫封装

在 lib/multi.c 中，curl_multi_notify_enable与curl_multi_notify_disable都通过CURL_MAPI_ENTER/CURL_MAPI_LEAVE宏进行守卫，这保证了多线程环境下对 multi handle 的并发 API 调用安全，随后委托给内部函数：

CURLMcode curl_multi_notify_enable(CURLM *m, unsigned int notification) { struct Curl_mapi_guard guard; CURLMcode mresult = CURLM_OK; if(CURL_MAPI_ENTER(&guard, m, multi_notify_enable, &mresult)) { mresult = Curl_mntfy_enable(m, notification); } CURL_MAPI_LEAVE(&guard); return mresult; }

启用/停用的核心逻辑：位集合管理

真正实现位于 lib/multi_ntfy.c：

CURLMcode Curl_mntfy_enable(struct Curl_multi *multi, unsigned int type) { if(type > CURLMNOTIFY_EASY_DONE) return CURLM_UNKNOWN_OPTION; Curl_uint32_bset_add(&multi->ntfy.enabled, type); return CURLM_OK; } CURLMcode Curl_mntfy_disable(struct Curl_multi *multi, unsigned int type) { if(type > CURLMNOTIFY_EASY_DONE) return CURLM_UNKNOWN_OPTION; Curl_uint32_bset_remove(&multi->ntfy.enabled, (uint32_t)type); return CURLM_OK; }

从中可以看出两点实现事实：

1. 类型合法性校验：当type大于当前最大类型CURLMNOTIFY_EASY_DONE（值为 1）时，直接返回CURLM_UNKNOWN_OPTION，从源码层面印证了错误码语义；
2. 启用集合：multi handle 内部通过uint32_bset（无符号 32 位位集合，见 uint-bset.h）记录所有已启用的通知类型，因此"重复启用不报错"天然成立——向集合中添加已存在的元素本就是幂等操作。

事件收集：回调存在 + 类型启用 双重校验

通知的收集入口是 lib/multi_ntfy.h 中的宏CURLM_NTFY和函数Curl_mntfy_add：

#define CURLM_NTFY(d, t) \ do { \ if((d) && (d)->multi && (d)->multi->ntfy.ntfy_cb) \ Curl_mntfy_add((d), (t)); \ } while(0)

而 lib/multi_ntfy.c 中的Curl_mntfy_add会进一步校验通知类型是否已启用以及是否处于失败状态，只有全部通过才会把事件追加到内部的 chunk 链表中排队等待分发。这正好对应文档中"回调安装 + 类型启用二者缺一不可"的约束。

从数据结构上看（lib/multi_ntfy.h），每个 multi handle 维护一个struct curl_multi_ntfy，包含回调指针ntfy_cb、用户数据ntfy_cb_data、启用集合enabled以及以 128 条为单位的mntfy_chunk事件队列。

触发点：事件从何而来

在 lib/multi.c 中可以看到两类通知的实际触发位置：

• CURLMNOTIFY_EASY_DONE：在状态机迁移到MSTATE_DONE时触发（lib/multi.c 的mstate_enter_done），以及直接从非 DID 状态跳转到MSTATE_COMPLETED时补发（lib/multi.c）；
• CURLMNOTIFY_INFO_READ：在multi_addmsg()中，仅当消息栈为空时触发（lib/multi.c），与文档中"消息加入空栈才通知"的描述完全一致。

分发时机：随驱动循环派发

收集到的事件不会立即调用回调，而是在合适的时机统一派发。Curl_mntfy_dispatch_all()（lib/multi_ntfy.c）实现了批量分发：从队列头部逐条取出事件，再次校验类型仍处于启用状态后调用ntfy_cb，并特别处理了"回调内部可能产生新通知"的递归追加场景。该分发函数由 lib/multi.c 与 lib/multi.c 在 multi 驱动循环（如curl_multi_perform路径）中调用。

值得一提的是，这个新机制把"持续轮询 multi handle 观察状态变化"的模式，转变成了"由 libcurl 主动推送"的事件驱动模式，这正是 CURLMOPT_NOTIFYFUNCTION.md 描述的设计意图。

回调的调用时机与限制：与普通回调的不同

CURLMOPT_NOTIFYFUNCTION.md 特别强调了该回调与 libcurl 其他回调的两点不同：

1. 可调用更多 libcurl API：除了curl_multi_perform、curl_multi_socket、curl_multi_socket_action、curl_multi_socket_all和curl_multi_cleanup之外，回调内可以调用 multi 与 easy 句柄上的几乎所有其他方法，包括向 multi handle 添加/移除 easy handle。这使得回调可以安全地在事件驱动模型中动态管理传输；
2. 调用时机不可预期：回调可能在应用程序与 libcurl 交互的任何时刻被调用，甚至可能发生在所有传输结束之后，也可能在curl_multi_cleanup()关闭缓存连接的过程中被调用。因此回调实现必须健壮，不能依赖调用时机的假设，且不要执行过于耗时或可能阻塞驱动循环的操作。

测试与 ABI 保障

仓库的 tests/data/test1135 测试用例通过test1135.pl校验CURL_EXTERN导出符号的顺序，其中明确包含curl_multi_notify_enable与curl_multi_notify_disable（见 tests/data/test1135），验证了这两个函数在导出表中的正确位置——因为 VMS 与 OS/400 构建依赖该顺序，破坏顺序会破坏二进制兼容性。此外，lib/libcurl.def（Windows 导出定义）与 projects/OS400/curl.inc.in 中也同步声明了这两个函数，确保跨平台导出一致。

总结与最佳实践

综合文档与源码，使用curl_multi_notify_enable的推荐实践如下：

1. 先安装回调再启用通知：通过curl_multi_setopt设置CURLMOPT_NOTIFYFUNCTION与CURLMOPT_NOTIFYDATA，随后调用curl_multi_notify_enable启用所需的通知类型；
2. 按需启用，可多类型并存：同时启用CURLMNOTIFY_INFO_READ与CURLMNOTIFY_EASY_DONE是常见组合；不再需要时用curl_multi_notify_disable关闭；
3. 检查返回值：调用后检查返回值是否为CURLM_OK，尤其注意CURLM_UNKNOWN_OPTION（类型越界）与CURLM_OUT_OF_MEMORY（内部队列分配失败）两类错误；
4. 回调内一次性消费消息：收到CURLMNOTIFY_INFO_READ后应立即用curl_multi_info_read()清空消息栈，否则下一次新消息加入空栈时不会再次通知；
5. 回调保持轻量：通知回调可能在驱动循环的关键路径上被调用，避免在其中做耗时操作；如需管理传输，利用其"可以添加/移除 easy handle"的扩展权限进行；
6. 区分内部句柄：回调收到的easy参数可能是 libcurl 内部句柄（如 DoH 场景），不要假设其一定来自应用层，也不要对其做超出文档允许的操作。

相关配套文档可进一步阅读 curl_multi_notify_disable.md、CURLMOPT_NOTIFYFUNCTION.md 与 CURLMOPT_NOTIFYDATA.md；源码可深入 lib/multi_ntfy.c 与 lib/multi_ntfy.h 了解完整的队列与分发实现。

【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl