libwebsockets 多线程安全接入事件循环:深入解析 minimal-http-client-attach 示例的 lws_system attach API

原创2026-10-13 09:31:262,253 阅读
文章标签:网络通信WebSocket嵌入式

libwebsockets 多线程安全接入事件循环:深入解析 minimal-http-client-attach 示例的 lws_system attach API

本篇围绕 minimal-http-client-attach 示例展开,讲解如何让一个与 libwebsockets 事件循环线程完全不同的线程,通过 lws_system_ops_t 的 (*attach) 机制安全地"挂载"到已存在的 lws_context 上,并让一次跨线程发起的 HTTP 客户端 GET 请求完全在事件循环线程的上下文里异步完成。读完本文,你将掌握 attach 回调的注册方式、事件循环侧的入队/出队/状态门控原理,以及示例代码逐段的实现细节,并了解如何用 pthread 锁正确包装非线程安全的内核辅助函数。

1. 示例要解决的问题:跨线程触达事件循环

libwebsockets 的协议处理(WebSocket、HTTP 客户端/服务端等)都运行在 lws_service() 事件循环所在线程的栈上下文中,其内部状态并非线程安全。因此其他线程不能直接调用 lws_client_connect_via_info() 等操作去驱动一次连接——这是多线程应用中最常见的踩坑点。

README 对该示例的定位是:

This demonstrates how other threads can reach out to an existing lws_context and join its event loop cleanly and safely.

示例用两个线程模拟"两个完全不同的代码库被链接到一起"的场景(源码注释原话见 minimal-http-client-attach.c 第 184~187 行):

  • lws 线程(lws_create()):负责创建 lws_context 并跑 while (lws_service(context, 0) >= 0) 事件循环,如同这段上下文由另一个模块"恰好"启动;
  • main 线程(代表外部代码库):不创建 context、不跑循环,只是拿到 context 指针后,通过 attach 机制向事件循环"预约"一个回调,在该回调里发起 HTTPS GET,然后本线程只需等待 lws 线程结束即可。

从 README 的运行日志可以看出完整时序:main 线程先打印自身 tid,随后 lws 线程打印 lws_create: tid ...,接着出现 attach_callback: called from tid 0x5c41700——注意这个 tid 与 lws 线程一致,证明回调确实是在事件循环线程上下文内被调用的,而不是在请求发起的 main 线程里。之后 HTTP 请求在事件循环内异步完成,日志依次出现 Connected to ..., http response: 200、多段 RECEIVE_CLIENT_HTTP_READ: read 4087/4096 分块读取,直到 LWS_CALLBACK_COMPLETED_CLIENT_HTTP,main 线程打印 finished 退出。

2. 构建方式与依赖

示例目录自带独立的 CMakeLists.txt,README 给出的构建命令为:

$ cmake . && make

Pthreads 是系统级硬性要求(README 原文:"Pthreads is required on your system")。CMake 侧则通过 LwsCheckRequirements 检查三个前置条件(CMakeLists.txt 第 12~15 行):

检查项 含义
require_pthreads(requirements) 必须有 pthreads 库
require_lws_config(LWS_ROLE_H1 1 requirements) lws 需启用 HTTP/1.1 角色
require_lws_config(LWS_WITH_CLIENT 1 requirements) lws 需启用客户端支持

三者满足且非 WIN32 时才编译出 lws-minimal-http-client-attach 可执行文件,并链接 PTHREAD_LIB。

3. 核心 API:attach 的架构与线程安全设计

attach 功能属于 lws_system 子系统,原型定义在 include/libwebsockets/lws-system.h(lws_attach_cb_t、lws_system_ops_t.attach、__lws_system_attach()),系统侧设计文档见 READMEs/README.lws_system.md 与 lib/system/README.md。其核心契约有四点:

(1)回调类型与"回调即移交"语义。

typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);

注册方提交回调后,自己的线程与栈随时可以退出;回调真正执行时运行在事件循环线程和栈上。README.lws_system 特别强调:正因为如此,opaque 若需要携带数据通常应指向堆内存——注册时所用的栈上下文在回调真正触发时可能早已销毁。

(2)状态门控(state gate)。 注册时传入的 state 参数指定"系统状态达到或越过该状态后才调用回调",通常传 LWS_SYSTATE_OPERATIONAL("user code can operate normally",见 lws-system.h 第 151 行)。系统状态机从 LWS_SYSTATE_CONTEXT_CREATED 逐级推进到 LWS_SYSTATE_OPERATIONAL,完整状态序列及其语义见 READMEs/README.lws_system.md 的状态表格:

libwebsockets 系统状态机概览

从源码结构看,门控判断发生在 lib/system/system.c 的 __lws_system_attach() 出队分支:只有当 pt->context->mgr_system.state >= (int)item->state 时,该 item 才会被从链表中摘出并交给调用方执行;未达标的 item 则留在链表里等待。

(3)入队/出队双模式。 (*attach) 的最后一个参数 get 区分两种用途(头文件注释,lws-system.h 第 209~225 行):

  • get == NULL:入队——为 cb/opaque/state 构造一项请求,挂到对应 pt 的 attach 链表头部;
  • get != NULL:出队——由事件循环线程调用,取出第一个状态已达标并已从链表摘除的 item,责任随之转移给调用方。

(4)锁必须由用户侧系统级实现持有。 内核辅助函数 __lws_system_attach() 明确声明是 non-threadsafe helper(头文件注释第 384~386 行:"a non-threadsafe helper only designed to be called from implementations of ... where system-specific locking has been applied around it")。设计意图是:把加锁逻辑外置到平台相关的 (*attach) 包装里,保证"入队"和"出队"走同一把锁,从而线程安全。

4. 逐段解析示例源码

4.1 事件循环线程:lws_create()

lws_create()(第 189~220 行)在独立 pthread 中完成 context 生命周期:

static void *
lws_create(void *d)
{
	struct lws_context_creation_info info;

	lwsl_user("%s: tid %p\n", __func__, (void *)(intptr_t)pthread_self());

	lws_context_info_defaults(&info, NULL);

	info.port = CONTEXT_PORT_NO_LISTEN;          /* 纯客户端,不监听 */
	info.options = LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT;
	info.system_ops = &ops;                      /* 关键:注入 attach 实现 */
	info.protocols = protocols;

	context = lws_create_context(&info);
	if (!context) { lwsl_err("lws init failed\n"); goto bail; }

	/* start the event loop */
	while (lws_service(context, 0) >= 0)
		;

	lws_context_destroy(context);

bail:
	pthread_exit(NULL);
}

要点:

  • CONTEXT_PORT_NO_LISTEN 表示该 context 不做任何服务端监听,纯粹跑客户端;
  • LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT 因为示例请求是 HTTPS(LCCSCF_USE_SSL);
  • info.system_ops = &ops 是把自定义 (*attach) 包装注入 context 的唯一入口——没有它,跨线程 attach 无法工作;
  • 全局变量 context 被 main 线程轮询等待,作为"事件循环线程已就绪"的同步信号。

4.2 自定义 attach 包装:pthread 锁包住内核函数

这是本示例最具复用价值的模式,直接照抄 (*attach) 的实现即可:

static pthread_mutex_t lock;

static int
lws_attach_with_pthreads_locking(struct lws_context *cx, int tsi,
				 lws_attach_cb_t cb, lws_system_states_t state,
				 void *opaque, struct lws_attach_item **get)
{
	int n;

	pthread_mutex_lock(&lock);
	/*
	 * We just provide system-specific locking around the lws non-threadsafe
	 * helper that adds and removes things from the pt list
	 */
	n = __lws_system_attach(cx, tsi, cb, state, opaque, get);
	pthread_mutex_unlock(&lock);

	return n;
}

static lws_system_ops_t ops = {
	.attach = lws_attach_with_pthreads_locking
};

注意:入队(main 线程调用)和出队(事件循环线程在 lws_system_do_attach() 里调用同一 (*attach) 且 cb = NULL、get = &item)都会经过这把锁,这正是第 3 节所述契约的落地。

4.3 main 线程:等待 context 就绪并注册回调

/* 等待 lws 线程把 context 建好,最多 ~300ms */
while (!context && n < 30) {
	n++;
	usleep(10000);
}
if (!context) { lwsl_err("%s: context didn't start\n", __func__); goto bail; }

/* 从非事件循环线程预约:状态达到 OPERATIONAL 时回调 attach_callback */
lws_system_get_ops(context)->attach(context, 0, attach_callback,
				    LWS_SYSTATE_OPERATIONAL,
				    NULL, NULL);

调用链解析:

  1. lws_system_get_ops(context) 从 context 取回 lws_system_ops_t *(头文件注释提醒"可能为 NULL 或成员为 NULL",所以生产代码应判空);
  2. ->attach(context, 0, attach_callback, LWS_SYSTATE_OPERATIONAL, NULL, NULL):tsi = 0(单线程服务索引)、opaque = NULL、get = NULL 表示纯入队;
  3. 入队侧内核实现在 lib/system/system.c(第 154~179 行)中 lws_zalloc() 出 lws_attach_item、填入 cb/opaque/state,lws_dll2_add_head() 挂到 pt->attach_owner 头部,然后调用 lws_cancel_service(context) 唤醒正在 poll 休眠的事件循环,使其立即回来处理这次入队;
  4. 注册返回后 main 线程不再持有任何 lws 资源,只需 pthread_join(lws_thread, &retval) 等待事件循环结束。

4.4 事件循环侧:出队与回调执行

事件循环每次醒来都会经由 lib/core/context.c(第 111~112 行)的状态通知器调用 lws_system_do_attach(&context->pt<a href="https://link.gitcode.com/i/e1258623f1a3dfc847e202f42a4f2993" target="_blank">n])(SUL 定时器路径也会触发,见 [lib/io/sorted-usec-list.c 第 50 行)。lws_system_do_attach() 的逻辑(第 214~259 行):

while (lws_dll2_count(&pt->attach_owner)) {
	...
	/* 系统锁只保护这次出队取 item 的操作 */
	if (pt->context->system_ops->attach(pt->context, pt->tid, NULL,
					    0, NULL, &item))
		return 1;
	if (!item)
		return 0;   /* 没有状态达标的 item,本次到此为止 */

	/* 从 lws 事件循环线程执行用户回调 */
	item->cb(pt->context, pt->tid, item->opaque);

	lws_free(item);    /* item 生命周期到此结束,由事件循环释放 */
}

即:出队也走同一把用户锁取走一个状态达标 item(不达标则 item == NULL 立即返回),随后在事件循环线程上直接调用 item->cb(),并负责释放 item。这就是 README 日志里 attach_callback: called from tid 0x5c41700 的来源。

4.5 attach_callback:在事件循环上下文内发起 HTTP GET

static void
attach_callback(struct lws_context *cx, int tsi, void *opaque)
{
	struct lws_client_connect_info i;

	/*
	 * Even though it was asked for from a different thread, we are called
	 * back by lws from the lws event loop thread context
	 */
	memset(&i, 0, sizeof i); /* otherwise uninitialized garbage */
	i.context = cx;
	i.ssl_connection = LCCSCF_USE_SSL;
	i.ssl_connection |= LCCSCF_H2_QUIRK_OVERFLOWS_TXCR |
			    LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM;
	i.port = 443;
	i.address = "warmcat.com";
	i.path = "/";
	i.host = i.address;
	i.origin = i.address;
	i.method = "GET";

	i.protocol = protocols[0].name;   /* "http" 协议槽 */

	lws_client_connect_via_info(&i);
}

关键细节:

  • memset(&i, 0, ...) 注释强调不清零就是垃圾值,lws_client_connect_info 各字段行为依赖零值默认语义;
  • 两个 LCCSCF_H2_QUIRK_* 标志是 HTTP/2 协商兼容性 workaround(当 ALPN 协商出 h2 时避免 txcredit 溢出和 END_STREAM 处理差异),对纯 h1 连接无副作用;
  • i.protocol = protocols[0].name 把这条 HTTP 客户端会话绑到名为 "http" 的协议槽,后续所有回调都会路由到该槽的 callback_http;
  • 回调函数体只做"预约"动作即返回——真正的 DNS 解析、TCP/TLS 握手、收发全部由事件循环异步驱动,这正是 README 注释所说 "we can set up our operations on the lws event loop and return so they can happen asynchronously"。

4.6 callback_http:HTTP 客户端回调处理与循环退出

协议槽回调 callback_http()(第 42~114 行)演示了 HTTP 客户端的标准回调序列,这也是理解示例日志的直接依据:

回调 reason 处理要点 对应日志
LWS_CALLBACK_CLIENT_CONNECTION_ERROR 打印错误串,lws_default_loop_exit(context) 终止循环 —
LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP lws_get_peer_simple() 取对端地址;status = lws_http_client_http_response(wsi) 解析响应行得到状态码 Connected to 46.105.127.147, http response: 200
LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ 已去掉头的分块内容逐块到达,打印长度即可;示例留有 #if 0 块可取消注释转储 HTML RECEIVE_CLIENT_HTTP_READ: read 4087 等
LWS_CALLBACK_RECEIVE_CLIENT_HTTP 用 lws_http_client_read(wsi, &px, &lenx) 主动读取未解析的原始 HTTP 内容(本示例仅消费不处理) —
LWS_CALLBACK_COMPLETED_CLIENT_HTTP / LWS_CALLBACK_CLOSED_CLIENT_HTTP bad = status != 200;lws_default_loop_exit(context) 请求退出循环;lws_cancel_service() 打断正在进行的 poll 等待 LWS_CALLBACK_COMPLETED_CLIENT_HTTP

lws_default_loop_exit() 与 lws_cancel_service() 的语义见 lws-service.h:前者让 lws_service() 返回 -1 从而退出循环("app that owns its loop to stop, ... the recommended way");后者对正在 poll 休眠的事件循环产生"同步中断",且允许从另一线程调用(第 102~103 行:"may be called from another thread while the context exists")——这也是 attach 机制能与事件循环干净协作的基础之一。回调尾部 return lws_callback_http_dummy(wsi, reason, user, in, len); 将未显式处理的 reason 交给默认实现。

5. 完整运行输出

按 README 记录,示例运行(依赖外网,目标 warmcat.com)的典型输出为:

$ ./lws-minimal-http-client-attach
[2019-12-31 18:30:49:3495] U: main: main thread tid 0x503e1c0
[2019-12-31 18:30:50:3584] U: LWS minimal http client attach
[2019-12-31 18:30:50:4002] U: lws_create: tid 0x5c41700
[2019-12-31 18:30:50:5727] E: callback_ntpc: set up system ops for set_clock
[2019-12-31 18:30:50:2110] N: callback_ntpc: Unix time: 1577817053
[2019-12-31 18:30:50:2136] U: attach_callback: called from tid 0x5c41700
[2019-12-31 18:30:51:8733] U: Connected to 46.105.127.147, http response: 200
[2019-12-31 18:30:51:8818] U: RECEIVE_CLIENT_HTTP_READ: read 4087
[2019-12-31 18:30:51:8823] U: RECEIVE_CLIENT_HTTP_READ: read 4096
[2019-12-31 18:30:51:8846] U: RECEIVE_CLIENT_HTTP_READ: read 4087
[2019-12-31 18:30:51:8847] U: RECEIVE_CLIENT_HTTP_READ: read 4096
[2019-12-31 18:30:51:8855] U: RECEIVE_CLIENT_HTTP_READ: read 4087
[2019-12-31 18:30:51:8856] U: RECEIVE_CLIENT_HTTP_READ: read 4096
[2019-12-31 18:30:51:8860] U: RECEIVE_CLIENT_HTTP_READ: read 1971
[2019-12-31 18:30:51:8873] U: LWS_CALLBACK_COMPLETED_CLIENT_HTTP
[2019-12-31 18:30:51:9629] U: main: finished

其中 callback_ntpc: set up system ops for set_clock 一行表明本库在 HTTPS 之前需要先确认系统时间可信(LWS_SYSTATE_TIME_VALID 门控),这正是 attach 必须等待 LWS_SYSTATE_OPERATIONAL(其前序状态含时间校验)而非 context 一创建就回调的原因。

6. 移植到你自己代码的注意事项

  1. 必须实现并注入 (*attach):在 lws_context_creation_info.system_ops 中提供带系统锁的包装,内部调用 __lws_system_attach();不加锁直接调用该辅助函数在多线程下是未定义行为;
  2. 回调只用于"预约",不要在里面做长阻塞:回调运行在事件循环线程,阻塞它等于阻塞整个 context 的所有连接;重活应转交给 scheduled events(SUL/sul 等机制);
  3. opaque 用堆指针:注册线程的栈在回调执行时通常已销毁(头文件注释亦如此说明);
  4. 判空 lws_system_get_ops() 的返回值:context 未设置 system_ops 时它可能为 NULL;
  5. 状态选择:常规客户端操作挂 LWS_SYSTATE_OPERATIONAL;若功能依赖网络/DNS 就绪,可参考 lws-system.h 第 105~161 行的完整状态枚举选择更精确的门控状态;
  6. 循环退出:完成或出错时用 lws_default_loop_exit() 让 lws_service() 返回 -1,如需打断休眠的 poll 再配合 lws_cancel_service()。

7. 延伸阅读

登录后查看全文
libwebsockets