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>
4.8 KiB
服务接口约定
这些条款整理工作区头文件和服务对外的生命周期语义。错误常量以 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 不同线程重叠执行提交和取消时,结果应与这两项操作的某个合法先后顺序一致。若尚未确认提交已经发布,取消可以先于提交生效,此后接受的提交仍产生一次回调;若取消作用于已经接受的安排且没有后续提交,则不再产生该次安排的回调。线程切换次数不表示某项安排已经发布。