# 逻辑线程运行时合同(版本 1) 实现必须符合本文件全部条款。全部数值、状态、排队和资源语义是本软件模型公开约定,不代表宿主内核行为。 ## 1. 范围与数值 R01. 这是普通 Linux 用户态的确定性软件模型。线程、信号、等待及资源都是逻辑状态;调用不创建系统线程,不发送系统信号,不访问时间、文件、网络或环境,不输出日志。 R02. 所有数值参数都是 std::uint32_t。thread_limit 的有效域为 1..16,unit_limit 为 1..64,线程 id 为 1..65535,每线程 units 为 1..64,signal 为 1..31,等待 token 为 1..4294967295;均含两端。无效值产生 RANGE。有效 units 大于当前池总量或剩余量属于 NO_UNITS,不属于 RANGE。每个逻辑线程最多有 31 个不同的 pending 信号。 R03. 信号 9 命名为 EXIT,信号 29 命名为 IO;它们只是 ID。只有 EXIT 具有退出效果,其余 1..31 的合法信号(包括 IO)均是普通投递。允许掩码的 bit (signal-1) 表示许可;bit 31 永远为 0,不按宿主系统信号编号推导其它效果。 R04. 返回码:OK=0,COALESCED=1,RANGE=-1,NOT_FOUND=-2,EXISTS=-3,BAD_STATE=-4,NO_SLOTS=-5,NO_UNITS=-6,NOT_ALLOWED=-7,PENDING=-8,BUSY=-9。Phase 为 NONE=0、RUNNABLE=1、WAITING=2、EXITED=3;Reason 为 NONE=0、SIGNAL=1、STOP=2;Event 为 IDLE=0、DELIVERED=1、INTERRUPTED=2、EXIT=3。 R05. Runtime(thread_limit, unit_limit) 有效时建立空实例:used_threads=used_units=0;没有线程、许可、pending 或等待。任一构造参数越界必须抛出 std::invalid_argument,不能建立部分实例;其它本合同 API 对定义域内或域外 uint32_t 参数均不抛异常。分别显式构造的实例完全独立;本合同不要求 Runtime 对象的复制或移动语义,观察器不复制或移动 Runtime 对象。 ## 2. 完整 API 与返回结构 R06. include/thread_signal.hpp 在 namespace thread_signal 中公开以下结构和方法;字段类型和方法签名必须保留。私有实现和内部文件可调整。容器 vector 的元素类型为 std::uint32_t,查询返回值为独立值,修改返回副本不得影响实例。 ```cpp struct StepResult { int rc; std::uint32_t event, signal, wait_token; std::int32_t exit_code; }; struct JoinResult { int rc; std::uint32_t reason; std::int32_t exit_code; std::uint32_t released_units; }; struct ThreadView { int rc; std::uint32_t id, phase, allowed, wait_token, reserved_units, reason; std::int32_t exit_code; }; struct PendingView { int rc; std::vector signals; }; struct PoolView { std::uint32_t thread_limit, unit_limit, used_threads, used_units; }; class Runtime { public: Runtime(std::uint32_t thread_limit, std::uint32_t unit_limit); int spawn(std::uint32_t id, std::uint32_t units); int allow(std::uint32_t id, std::uint32_t signal); int deny(std::uint32_t id, std::uint32_t signal); int post(std::uint32_t id, std::uint32_t signal); int arm_wait(std::uint32_t id, std::uint32_t token); StepResult step(std::uint32_t id); JoinResult join(std::uint32_t id); JoinResult stop(std::uint32_t id); ThreadView thread(std::uint32_t id) const; PendingView pending(std::uint32_t id) const; PoolView pool() const; }; ``` R07. StepResult 或 JoinResult 的 rc<0 时,其余所有字段为 0。ThreadView 的 rc<0 时,其余所有字段为 0;PendingView 的 rc<0 时 signals 为空。成功查询、失败调用和 COALESCED 均不得引入未说明的副作用。除 spawn/allow/deny/post/arm_wait/step/join/stop 明确规定的效果外,状态不变。 R08. 错误优先级严格按下列各 API 顺序:先检查该方法全部参数的数值域;存在性及业务状态校验随后进行。域外参数不得以 NOT_FOUND、BAD_STATE、COALESCED 或资源错误掩盖。任何返回 rc<0 的调用整体原子,许可、队列、等待、线程、完成记录和资源余额全部保持原值。这里的失败原子性不限制成功操作的明示副作用:成功 EXIT step 改变生命周期但继续占用预留,成功 join/stop 删除线程并归还计费;不得把这些成功效果一并回滚或提前归还。 ## 3. 建立和许可 R09. spawn(id, units) 的顺序为 RANGE、EXISTS、NO_SLOTS、NO_UNITS、OK。已有 id(包括尚未 join 的 EXITED)产生 EXISTS;used_threads==thread_limit 产生 NO_SLOTS;used_units+units>unit_limit 产生 NO_UNITS。成功预留 1 线程槽及 units 工作单元,建立 RUNNABLE、allowed=0、wait_token=0、reserved_units=units、reason=NONE、exit_code=0、pending 为空的新记录。used_threads、used_units 必须相应增加。 R10. allow(id, signal) 和 deny(id, signal) 的顺序均为 RANGE、NOT_FOUND、BAD_STATE、OK;EXITED 属于 BAD_STATE,RUNNABLE 与 WAITING 均可操作。allow 设相应许可 bit,deny 清该 bit;已允许再 allow、已拒绝再 deny 均返回 OK。其它 bit 不变;操作不改变 Phase、wait_token、资源、退出信息或其它线程。 R11. allow/deny 只规定之后的 post 是否可接收。deny 不能撤销或删除之前成功接收的 pending,不能改变其 FIFO 位置;allow 不能补入曾被拒绝的 post。特别是已接收的 EXIT,在之后 deny(EXIT) 后仍必须由 step 正常退出;step 不得按当前许可再次过滤既有 pending。先 deny 再 post 与先 post 再 deny 的结果不同。 ## 4. 接收与等待 R12. post(id, signal) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、NOT_ALLOWED、COALESCED、OK;EXITED 属于 BAD_STATE。当前许可 bit 为 0 时返回 NOT_ALLOWED,即使该 signal 已在 pending。当前许可为 1 且 signal 已在 pending 时返回 COALESCED=1,队列完全不变;否则以 OK 接收并追加到 FIFO 队尾。不因等待而立即投递,不修改 Phase 或 token,不消耗资源。 R13. 每线程的 pending 按首次成功 post 的顺序排列。同一 signal 同时最多一项;重复 post 不移动其位置;step 消费后允许再次接收并排在当时队尾。不同线程完全独立。不得按 signal 数值排序,不得以位图扫描顺序代替 FIFO。 R14. arm_wait(id, token) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、PENDING、OK。只有 RUNNABLE 可建立等待;WAITING(包括相同 token 再调用)和 EXITED 均 BAD_STATE。RUNNABLE 且 pending 非空返回 PENDING,不能偷消费。成功转为 WAITING 并保存 token;其它字段和资源不变。token 只用于标识原始等待,可以在不同线程或以后的等待中重复使用。 ## 5. 显式投递 R15. step(id) 的顺序为 RANGE、NOT_FOUND、BAD_STATE、OK;EXITED 属于 BAD_STATE。没有 pending 时返回 {OK,IDLE,0,0,0},无论 RUNNABLE 或 WAITING 均不改变状态,不制造唤醒。 R16. 有 pending 时,step 只消费 FIFO 第一项。普通 signal 在 RUNNABLE 时返回 {OK,DELIVERED,signal,0,0} 并保持 RUNNABLE;在 WAITING 时返回 {OK,INTERRUPTED,signal,原token,0},转为 RUNNABLE 并清 wait_token。其它 pending 保留原顺序;资源、许可、退出信息不变。 R17. 被消费的 signal 为 EXIT 时,step 返回 {OK,EXIT,9,原token或0,-9},转为 EXITED,reason=SIGNAL、exit_code=-9,清等待和全部 pending。reserved_units、allowed、线程槽及单位预留仍保留,直至 join/stop 收集。此规则同样适用于从未等待的线程和 WAITING 线程,也适用于当前 EXIT 许可已被 deny 的线程。 ## 6. 收集与资源 R18. join(id) 的顺序为 RANGE、NOT_FOUND、BUSY、OK;RUNNABLE 与 WAITING 均 BUSY。EXITED 时成功返回 {OK,原reason,原exit_code,原reserved_units},原子删除线程,归还 1 槽及全部预留单位;其它线程不变。此前是否等待、普通中断、deny 或重复 post,均不能改变应归还的 units。 R19. stop(id) 的顺序为 RANGE、NOT_FOUND、OK。RUNNABLE/WAITING 先同步结束(reason=STOP、exit_code=-125),丢弃 pending 并清等待,然后在同一调用内收集;EXITED 则保留原 reason 和 exit_code 并直接收集。成功返回 {OK,最终reason,最终exit_code,原reserved_units},删除线程并归还 1 槽及全部单位。stop 不需要 EXIT 许可,不等待后续 step,未接收的系统信号与本模型无关。 R20. join/stop 成功后 thread/pending/step/allow/deny/post/arm_wait/join/stop 对该 id 均 NOT_FOUND(参数域优先规则仍适用);重复收集不能再次归还。之后允许 spawn 复用该 id,重建完全干净的 RUNNABLE 记录;旧许可、pending、等待、退出原因和资源凭据均不得迁移。used_threads 与 used_units 在任何可观察时刻分别等于所有尚存在记录的数量与 reserved_units 之和,含 EXITED 记录;范围分别为 0..thread_limit、0..unit_limit。 ## 7. 独立查询 R21. thread(id) 的顺序为 RANGE、NOT_FOUND、OK;成功逐字段返回该 id 的当前公开记录。RUNNABLE 的 wait_token 为0,WAITING 的 token 为原等待值,EXITED 的 token 为0;只有 EXITED 有非 NONE reason 和非0 exit_code。reserved_units 从 spawn 至收集保持不变,allowed 可在 EXITED 保留最后许可值。查询无副作用。 R22. pending(id) 的顺序为 RANGE、NOT_FOUND、OK;成功返回当前 FIFO 的完整独立副本,EXITED 返回 OK/空队列。pool() 总是返回本实例构造容量及当前 used_threads/used_units 的独立副本。重复查询不能消费队列、唤醒、退出、回收或改变任意实例;不能用 thread 的观察代替另一个 API 的行为。 ## 8. 构建与原始观察协议 R23. 使用 C++17 标准库离线构建,不能引入第三方依赖。公开构建 argv 为 ["make", "observe"],产生 build/observe;运行 argv 为 ["./build/observe"],输入来自 stdin。正式评分会将五个候选文件和同一公开 tools/observe.cpp 重新编译,不使用已有构建产物。只交付并评分这五个候选文件,新增文件不会被收集;必须保留完整 API 与上述行为。 R24. observer 输入为 ASCII/LF 的命令行,每次进程最多4096行。首行且仅有一行 NEW thread_limit unit_limit,构造实例0并选中它;可另有一行 ALT thread_limit unit_limit,构造实例1但不改变选择;SELECT 0 或 SELECT 1 选择已经建立的实例。其余命令操作当前选择的实例:SPAWN id units、ALLOW id signal、DENY id signal、POST id signal、WAIT id token、STEP id、JOIN id、STOP id、THREAD id、PENDING id、POOL、COPY_THREAD id、COPY_PENDING id、COPY_POOL。所有参数是0..4294967295的无符号十进制整数,无空行、未知命令、重复NEW/ALT或未建立实例的选择。无效NEW后输入到此结束;无效ALT后实例0继续可用,但不能SELECT 1。其它脚本继续直到EOF;只保证此语法内输入,不要求处理其它字节。 R25. 每条命令恰好输出1行:NEW/ALT成功为 "命令名 OK",无效构造为 "命令名 INVALID_ARGUMENT";SELECT为 "SELECT index"。整数API结果为 "命令名 rc";STEP为 "STEP rc event signal wait_token exit_code";JOIN/STOP为 "命令名 rc reason exit_code released_units";THREAD为 "THREAD rc id phase allowed wait_token reserved_units reason exit_code";PENDING为 "PENDING rc count signal..."(空时无尾部空格);POOL为 "POOL thread_limit unit_limit used_threads used_units"。COPY_*按对应查询的格式输出,仅把首字段替换为COPY_THREAD、COPY_PENDING或COPY_POOL。所有整数为最短十进制,无正号,无前导0(0本身除外),字段间一个ASCII空格,每行恰好以单字节LF结束,无其它stdout字节。 R26. COPY_THREAD先取得thread返回值并将该本地副本全部字段置0,再调用thread打印后一次原始返回;COPY_PENDING先取得pending返回值、把本地副本rc置0并把signals改为[31],再调用pending打印后一次原始返回;COPY_POOL先取得pool返回值并把该本地副本全部字段置0,再调用pool打印后一次原始返回。ALT/SELECT和这些命令都只负责选择对象或修改本地返回副本,不含断言。库本身不能向stdout/stderr输出;observer/候选正常退出码为0,stderr必须为空。stdout以binary exact bytes核对,不允许额外空行、CRLF、NUL、非法UTF-8、缺行或诊断。正式harness只调用/打印,预期与断言在独立Python进程。 R27. 评分使用有效输入域中的组合、公开错误域、容量端点、信号与线程交错和确定性的长序列。成功必须来自全部必需行为,不由“最后一次池为空”或某个快照替代中间返回值;不要求内部数据结构、具体算法、代码布局或与某一参考实现相同。实现符合本合同全部条款即可。