libwebsockets中正确使用lws_close_reason()的技术指南

问题背景

在libwebsockets项目中，开发者gmabey在使用lws_close_reason()函数时遇到了断言失败的问题。具体表现为调用lws_close_reason()时，assert(lwsi_role_ws(wsi))断言失败。经过项目维护者的分析，发现这是一个典型的WebSocket连接管理问题。

核心问题分析

问题的根源在于开发者错误地在LWS_CALLBACK_EVENT_WAIT_CANCELLED回调中尝试使用lws_close_reason()函数。这个回调与其他WebSocket事件回调有本质区别：

1. 无关联的WebSocket连接：EVENT_WAIT_CANCELLED回调与特定WebSocket连接无关，它是事件循环本身的回调
2. 虚拟wsi结构：该回调使用一个虚拟的wsi结构体，仅用于提取上下文和虚拟主机信息
3. 多连接场景问题：如果有多个WebSocket连接，该回调无法确定应该操作哪个连接

正确使用lws_close_reason()

要在libwebsockets中正确发送关闭原因，需要注意以下几点：

1. 合法的调用时机

lws_close_reason()只能在以下WebSocket相关回调中使用：

• LWS_CALLBACK_CLIENT_RECEIVE
• LWS_CALLBACK_CLIENT_WRITEABLE
• 其他明确与特定WebSocket连接关联的回调

2. 连接生命周期管理

开发者需要自行管理WebSocket连接的生命周期：

• 在LWS_CALLBACK_ESTABLISHED回调中记录活跃连接
• 在LWS_CALLBACK_CLIENT_CONNECTION_ERROR和LWS_CALLBACK_CLOSED回调中移除已关闭连接
• 维护一个当前活跃连接的列表

3. 线程安全考虑

libwebsockets不是线程安全的，如果需要在其他线程操作WebSocket连接：

• 使用共享内存块进行线程间通信
• 操作前确认目标连接仍然存在
• 考虑使用互斥锁保护共享数据

解决方案示例

以下是处理WebSocket关闭的推荐模式：

// 全局或上下文相关的连接列表
std::vector<struct lws*> active_connections;
std::mutex connections_mutex;

// 在ESTABLISHED回调中添加连接
case LWS_CALLBACK_ESTABLISHED:
{
    std::lock_guard<std::mutex> lock(connections_mutex);
    active_connections.push_back(wsi);
    break;
}

// 在关闭相关回调中移除连接
case LWS_CALLBACK_CLOSED:
case LWS_CALLBACK_CLIENT_CONNECTION_ERROR:
{
    std::lock_guard<std::mutex> lock(connections_mutex);
    active_connections.erase(std::remove(active_connections.begin(), 
                                       active_connections.end(), 
                                       wsi), 
                           active_connections.end());
    break;
}

// 安全地关闭连接
void safe_close_connection(struct lws* wsi, int close_code)
{
    std::lock_guard<std::mutex> lock(connections_mutex);
    if (std::find(active_connections.begin(), 
                 active_connections.end(), 
                 wsi) != active_connections.end()) {
        lws_close_reason(wsi, (enum lws_close_status)close_code, 
                        (unsigned char*)reason_str, reason_len);
    }
}

最佳实践建议

1. 避免在非连接特定回调中使用wsi：特别是EVENT_WAIT_CANCELLED这类系统级回调
2. 实现连接追踪机制：维护活跃连接列表是管理多个WebSocket连接的基础
3. 考虑连接状态验证：在操作任何wsi前，确认它仍然处于活跃状态
4. 线程安全设计：如果必须跨线程操作，确保有适当的同步机制

通过遵循这些原则，开发者可以避免常见的WebSocket连接管理陷阱，确保lws_close_reason()等函数被正确使用。