Batch 28 commit b7fd210 gave ESP NVS iterator versions and RT-Thread workqueue timer state as HARD: all 3 attempts of each ran out of model context, which counts as a failure. Each task comes from the commit Qwen measured, its digest matches, and it is still present at the batch branch head. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
29 lines
4.8 KiB
Markdown
29 lines
4.8 KiB
Markdown
# 服务接口约定
|
||
|
||
这些条款整理工作区头文件和服务对外的生命周期语义。错误常量以 `include/rtdef.h` 为准。本配置使用 libc 错误码:`RT_EOK=0`、`RT_ERROR=255`、`RT_EBUSY=EBUSY`。
|
||
|
||
**R01** `rt_work_init` 绑定回调与不透明用户数据。`rt_workqueue_create` 建立独立工作线程。工作回调由工作线程调用,收到原工作指针和原用户数据;空队列不产生回调。
|
||
|
||
**R02** `rt_workqueue_submit_work(queue, work, ticks)` 的 `ticks` 是相对于本次提交的 tick 间隔,小于 `RT_TICK_MAX/2`;对没有仍在倒计时的安排,零间隔与 `rt_workqueue_dowork` 将工作加入待执行队列,返回 `RT_EOK`。普通待执行工作按加入顺序执行。`rt_workqueue_urgent_work` 将没有仍在倒计时的工作放到待执行队列前端并返回 `RT_EOK`。
|
||
|
||
**R03** 正间隔的工作在期限前不执行,到期后进入工作线程执行一次;尚未到期的工作再次以正间隔提交时采用本次提交的期限,不保留旧期限。工作执行完成后可以再次提交,也可从工作回调中再次提交;每次被接受的安排只执行一次。
|
||
|
||
**R04** `rt_workqueue_cancel_work` 移除尚未执行的安排,成功返回 `RT_EOK`;取消已完成且没有新安排的工作也返回 `RT_EOK`。在工作自身回调内取消正在执行的工作返回 `-RT_EBUSY`,不撤销当前调用。
|
||
|
||
**R05** `rt_workqueue_cancel_work_sync` 对尚未执行的安排完成取消并返回 `RT_EOK`。`rt_workqueue_cancel_all_work` 取消队列中全部待执行和未到期工作并返回 `RT_EOK`。取消后的工作可以重新提交;一个工作可在前次安排完成后提交到另一个队列。
|
||
|
||
**R06** 重叠的正间隔重新提交若返回 `RT_EOK`,须在新期限建立一次安排;已经开始的旧回调可以完成一次。若不能更改进行中的分发,可以返回 `-RT_ERROR`,此时原分发继续完成一次。取消若返回 `RT_EOK`,不再开始被取消安排的回调;已开始的回调可以完成。不能取消进行中的分发时返回 `-RT_ERROR`,原分发继续完成一次。
|
||
|
||
**R07** `rt_timer_init` 建立尚未启动的计时器并绑定回调和用户参数。`rt_timer_start` 在当前 tick 加上间隔处安排回调,成功返回 `RT_EOK`。单次计时器到期回调一次后保持停止,周期计时器在每次回调完成后从当前 tick 重新计时。相同期限按启动顺序分发;软计时器由 timer 线程分发,硬计时器由 `rt_timer_check` 分发。
|
||
|
||
**R08** `rt_timer_control` 的 `GET_TIME` 返回配置间隔,`GET_STATE` 返回启动或停止状态。`SET_TIME` 更新间隔并停止已有计时,只有再次启动后才按新间隔计时;此命令返回 `RT_EOK`。`SET_PERIODIC` 与 `SET_ONESHOT` 修改后续到期策略并返回 `RT_EOK`。
|
||
|
||
**R09** `rt_timer_stop` 对已启动的计时器停止后续回调并返回 `RT_EOK`,对已停止的计时器返回 `-RT_ERROR`。计时器自己的回调正在处理时,启动同一个计时器返回 `-RT_ERROR`;这次失败不改变周期计时器的正常后续计时。在回调内可以设置间隔或停止计时;设置间隔会停止周期重复,回调内对自身的随后启动仍返回 `-RT_ERROR`。回调返回后可以再次启动。回调内启动另一个尚未处理的计时器正常成功。
|
||
|
||
**R10** tick 是 32 位无符号计数,所有时间差小于半个计数范围,以模算术判断到期;间隔可以为零。计时器 enter hook 在调用超时回调之前通知,exit hook 在超时回调返回后通知。这组通知描述计时器路径,不表示工作已经发布或工作回调仍未发生;工作队列也可采用不经过这组通知的延迟调度路径。应用可以观察通知,不应据此推断工作内部阶段或写服务内部链表、标志。
|
||
|
||
**R11** `os_init` 初始化用户态平台。`os_tick(tick)` 只设置当前 tick 并唤醒到期的 IPC 等待线程。`os_step(name)` 恢复一个给定名字的可运行线程,直到该线程阻塞、调度或在中断屏蔽解除处让出;没有该线程可运行时返回零。传空名字选择第一个可运行线程。`os_drain` 反复推进所有可运行线程直到空闲。线程运行顺序由创建顺序决定,timer 线程先于示例中的工作线程;中断屏蔽和临界区内不切换。推进硬计时器需在设 tick 后显式调用 `rt_timer_check`。平台没有真实 ISR、串口或墙钟依赖。
|
||
|
||
**R12** 不同线程重叠执行提交和取消时,结果应与这两项操作的某个合法先后顺序一致。若尚未确认提交已经发布,取消可以先于提交生效,此后接受的提交仍产生一次回调;若取消作用于已经接受的安排且没有后续提交,则不再产生该次安排的回调。线程切换次数不表示某项安排已经发布。
|
||
|