sysplus - sys库的强力补充

一. `sysplus` 模块核心功能概述

sysplus 是 sys 模块的扩展库，主要提供增强的任务消息机制和 cwait 机制，用于更灵活的任务管理和异步通信。常用于网络通信（如 socket、libnet、http 库）和复杂任务场景。

sys 模块是 LuatOS 的核心库，提供任务管理、定时器、事件机制等基础功能，是开发网络通信、传感器控制等应用的核心工具。

建议 sysplus 和 sys 一起阅读。

二. API 函数详解

(1) 任务与消息管理

sysplus.taskInitEx(func, taskName, cbFun, ...)

功能：创建一个任务线程，在模块最末行调用该函数并注册模块中的任务函数，main.lua 导入该模块即可。
参数：
- func：任务函数名，用于 resume 唤醒时调用。
- taskName：任务名称（字符串，全局唯一）。
- cbFun：回调函数，用于处理非目标消息。
- ...：传递给 func 的可变参数。
- 返回值：任务线程号（number）。
- 示例：

local function taskFunc()
    while true do
        local msg = sys.wait()  -- 等待消息
        if msg.target == "start" then
            log.info("Task Started")
        end
    end
end

sysplus.taskInitEx(taskFunc, "task1", function(msg)
    log.warn("Received non-target message:", msg)
end)

sysplus.taskDel(taskName)

功能：删除由 taskInitEx 创建的任务线程。
参数：taskName（任务名称）。
返回值：无。
示例：

sysplus.taskDel("task1")  -- 删除名为 "task1" 的任务

sysplus.cleanMsg(taskName)

功能：清除指定任务的消息队列。
参数：taskName（任务名称）。
返回值：无。
示例：

sysplus.cleanMsg("task1")  -- 清空 "task1" 的消息队列

(2) 消息传递机制

sysplus.waitMsg(taskName, target, timeout)

功能：等待指定目标消息，支持超时控制。
参数：
- taskName：任务名称（接收消息的任务 ID）。
- target：目标消息标识（字符串或 nil 表示接收任意消息）。
- timeout：超时时间（毫秒，nil 表示无限等待）。
- 返回值：
- 成功：返回消息 table（包含 target、arg2、arg3、arg4 等参数）。
- 超时：返回 false。
- 注意：会自动注册全局函数 sys_wait，需避免命名冲突。
- 示例：

local msg = sysplus.waitMsg("task1", "data", 2000)
if msg then
    log.info("Received:", msg.target, msg.arg2)
else
    log.warn("Timeout")
end

sysplus.sendMsg(taskName, target, arg2, arg3, arg4)

功能：向指定任务发送消息。
参数：
- taskName：目标任务名称。
- target：消息标识（接收方 waitMsg 的 target 匹配项）。
- arg2~arg4：附加参数（可选）。
- 返回值：true（成功）或 false（失败）。
- 注意：自动注册全局函数 sys_send，需避免命名冲突。
- 示例：

-- 向任务 "task1" 发送目标为 "data" 的消息，携带参数 100 和 "ok"
sysplus.sendMsg("task1", "data", 100, "ok")

三. 使用场景与示例代码

示例 1：任务创建与消息通信

-- 定义任务函数
local function taskFunc()
    while true do
        local msg = sysplus.waitMsg("task1", "data", -1)  -- 无限等待 "**data**" 消息
        if msg then
            log.info("Received Data:", msg.arg2, msg.arg3)
        end
    end
end

-- 创建任务
sysplus.taskInitEx(taskFunc, "task1", function(msg)
    log.warn("Unknown message:", msg)
end)

-- 主线程发送消息
sysplus.sendMsg("task1", "data", 42, "Hello from main")

示例 2：超时控制与消息清理

-- 等待消息并处理超时
local msg = sysplus.waitMsg("task2", "timeout_test", 1000)
if not msg then
    log.error("Message timeout!")
    sysplus.cleanMsg("task2")  -- 清理消息队列
end

四. 注意事项

1. 任务命名唯一性：

taskName 必须全局唯一，避免重复导致任务覆盖或冲突。

2. 全局函数注册：

sysplus.waitMsg 和 sysplus.sendMsg 会自动注册全局函数 sys_wait 和 sys_send，需确保不与其他代码冲突。

3. 消息队列限制：

消息队列容量有限，需及时处理消息或调用 sysplus.cleanMsg 避免队列溢出。

4. 协程与阻塞：

sysplus.waitMsg 是阻塞操作，建议在独立任务中使用，避免阻塞主线程。

5. 参数传递限制：

sendMsg 最多支持 4 个参数（target + 3 个附加参数），需按需设计消息结构。

五. 常见问题

1. Q：如何处理消息队列溢出？

定期调用 sysplus.cleanMsg 或在 cbFun 中清理无效消息。

2. Q：waitMsg 的超时时间如何设置？

timeout 为 nil 表示无限等待，0 表示立即返回，负数同 nil。

3. Q：任务被删除后如何清理资源？

使用 sysplus.taskDel 同时会自动清理相关消息队列。