From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27, 11 canonical families), 38 skipped for scope or duplication. Each task has at least one independent contract-edge defect, boundary types rotate, and public docs state trap clauses as plain contract prose. Claude reviewed 63/63 USABLE against current digests. Difficulty is unmeasured. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.8 KiB
7.8 KiB
清单发送协议 v1
对象与生命周期
- 所有数值均按字节计。固定上限:12 段,每段 0..256 字节,总计最多 3072 字节;窗口宽度 1..4。所有对象只由一个线程调用,无硬件、时间或网络语义。
vt_job_open(job, spans, count)在成功时复制 count 个描述符,保存原数据指针,设置 ready=1、count,重置 calls/last_error/done。载荷不复制、不修改,调用者须使载荷在该 job 使用期间有效且不变;原始描述符数组可以立即修改或释放。- count=0 时 spans 可以为 NULL;空段的 data 也可以为 NULL。非空段 data 必须非 NULL。job=NULL、count>12、count 非零但 spans=NULL、任一长度>256 或非空段 NULL,均返回 -EINVAL,现有 job 的全部内容不变;成功返回 0。重新 open 替换旧清单,但不影响外部 book/device。
- 游标表示已接受前缀:done 为接受总数;index/offset 指向下一个未接受字节,跳过所有空段。完成时 index=count、offset=0;空清单及全空段清单在 open 后即为此规范位置。total 是所有段长之和。未 open 的 job 由调用者置零,不能发送。
vt_book_reset(book)将 bytes/requests/completed/failures/pauses 全部置零;book=NULL 无动作。book 与 job 生命周期独立,多次 open、多个 job 均可共用一个 book;不要求 counter 溢出行为,输入累计总数须在 uint64_t 范围内。
发送 API
vt_submit(job, book, quota, width, sender, context)的 quota 合法值为 1..3072,width 为 1..4;job/book/sender 不得 NULL,job 必须 ready。非法时返回 -EINVAL,job/book 不变且不调用 sender。context 原样传给 sender,可以为 NULL。- 每个合法 submit 把 job.last_error 清零,并从当前游标开始最多接受 quota 个字节;到清单尾、零返回或终止错误时提前停止。已完成或空清单返回 0,不调用 sender,但仍算一次合法请求。
- 每次 sender(context, window, count) 提供当前后缀中按原顺序排列的前 width 个非空段;首段从 offset 开始,末段按本次剩余 quota 截断。不得合并相邻原始段,不得发送零长段,不得越过 quota,也不得省略可放入窗口的段。count 在 1..width,指针指向原载荷的相应位置。
- sender 返回正数 n 表示窗口串接后的前 n 字节已被接收;立即推进游标,跨越任意多个段与空段。n 小于提供量时继续发送剩余部分,不重发已接受字节。n 大于提供量视为 EPROTO,该次不接受任何字节并停止。
- sender 返回 -EINTR 时原样重试相同窗口,计调用次数,无接受字节,不记录 failures;测试与使用方须保证中断序列有限。返回 0 时停止本次请求,游标不动,pauses 加一,last_error 保持 0。返回 -EAGAIN/-EIO/-ENOSPC 时停止,last_error 记录正 errno,failures 加一。后续 submit 可从已接受位置继续。
- 每次实际调用 sender 都令 job.calls 加一,包括中断、零和错误;合法请求最终令 book.requests 加一,book.bytes 只加该请求真正接受的字节。即使后续出错,已接受字节不得撤销。若本次把一个原本未完成的清单推至完成,book.completed 加一,仅此一次;错误或暂停即使发生在已部分接受之后也要计入各自计数。
- 返回值:本请求已接受字节>0 时始终返回该正数,包括随后停止于错误或零;无接受字节时,终止错误返回负 errno,否则返回 0。返回正数与 last_error 非零可同时出现。剩余额度用尽不算暂停;EINTR 不成为 last_error。
vt_cursor_reset(cursor, spans, count)、vt_cursor_window(job,budget,width,out)、vt_cursor_advance(job,amount)是同一库的低层接口。前提为有效对象与已验证描述符;window 的 budget 在 0..total-done、width 在 1..4,out 容纳 4 段,返回段数且不改 job;advance 的 amount 在 0..total-done。它们分别建立第4条游标、构建第8条窗口、接受第9条前缀。budget=0 返回0,amount=0只保持规范游标。vt_book_finish(book,accepted,error,paused,completed)是低层结算接口:参数分别是有效 book、此次接受字节、非负终止 errno、0/1暂停标志、0/1新完成标志,按照第11条更新各计数并返回第12条值。不清除已有累计值。
可编程接收器与观察
vt_device_reset(device, observations)清除接收字节、调用次数、脚本和位置,并保存观察流;observations=NULL 不输出 CALL。device 非 NULL。接收缓存容量65536,调用者保证一次 reset 之间累计合法接收量不超过此值。vt_device_script(device,values,count)用新脚本替换旧脚本并将位置归零,不改变已接收字节与调用次数。count 为0..64,count=0时values可NULL。每项合法值为0..3073或-EINTR/-EAGAIN/-EIO/-ENOSPC;非法 count、NULL或值返回-EINVAL,device全部不变;成功0。每次发送先消费一个脚本值;用尽后返回此次提供的总量且不再增加脚本位置。vt_device_send是 sender:calls 加一,记录 CALL,返回脚本值或默认总量。只有正返回且不超过提供量时,按段顺序把前 n 字节附加到接收缓存。负值、零及超过提供量均不附加字节。仅使用文档允许的缓存范围;不测试超出容量。errno 数值使用 Linux errno.h 的定义。vt_print_hex(stream,data,count)输出小写两位十六进制串;count=0输出单个-。vt_print_state输出下述 STATE。两者不改任何对象。CALL 格式:CALL count len:hex ... => result,每段各一个 len:hex;所有观察的字段由空白分隔,允许等价的空白排版。- STATE 字段顺序:
STATE ready count index offset done total job.calls last_error book.bytes book.requests book.completed book.failures book.pauses device.calls script_position received_length received_hex。没有载荷时 received_hex 为-;状态输出包括全部已接收数据,而非仅本请求新增部分。
文本重放入口
- 文本输入是 ASCII 命令行,行长(不含末尾LF)<=8191字节,每行最多68个空白分隔字段,空白仅为空格、tab、CR、LF;VT、FF不能作空白或混入数词。EOF 前最后一行可以不带 LF,空 stdin 不产生输出。空行、未知命令、参数缺失/多余或超出参数约束均返回 -EINVAL,不改变对象;不要求处理超出行长和字段数上限的输入。size数词为可选单个
+后跟至少一位ASCII数字0..9,拒绝负号(含-0);脚本项数词为可选单个+或-后跟至少一位ASCII数字。两者都允许任意多个前导0,不允许其他前缀、后缀或词内字元。十六进制大小写均允许;除单独-表示空段外,不允许奇数长度或非十六进制字元。 R把 job/book/device 全部重置为零并接回当前输出流;O count hex...按第2..4条创建清单,恰好 count 个hex字段;P count value...按第16条设脚本,恰好 count 个值;S quota width调用 submit;Q仅查询并返回0。命令本身的解析失败不能消费脚本或改变旧载荷。- 每个输入行有从1起递增的 step,先输出该行执行中发生的所有 CALL,随后
RESULT step return_value和一行 STATE。R 不重置 step。vt_console(input,output)与主程序的语义一致,正常EOF返回0;流I/O错误返回2。stderr仅诊断,不属于协议;构建必须成功,不要求特定诊断字节或格式。
交付
- 必须符合本文件全部条款和头文件ABI,并可由
make离线构建。评分仅冻结 README 列明的7个文件,其他文件固定。隐藏输入只改变清单数据、合法边界、错误组合、重用次序与文档已列明的非法参数;不要求修改未列明的文件。