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>
17 lines
5.2 KiB
Markdown
17 lines
5.2 KiB
Markdown
# Stream journal library
|
|
|
|
R01. `stream.h` declares the C11 API. The capacities of the incoming and outgoing FIFO queues and the largest pump quota are 64 bytes. The three console channels hold independent `stream` values. The port callbacks are synchronous, deterministic substitutes for system calls; no network or signal handlers are used.
|
|
R02. Status values are OK=0, WAIT=1, END=2, FAULT=3, CLOSED=4, INVALID=5, FULL=6, BUSY=7. Every API pointer names writable storage of the declared type, and every input byte pointer covers its count; a zero count does not access that pointer. Callers preserve the declared structure fields and do not edit initialized queues directly.
|
|
R03. `ring_reset` makes a FIFO empty. `ring_space` returns 64 minus its size. `ring_append` appends count bytes in order, with count at most the available space. `ring_copy` copies min(size,limit) oldest bytes without mutation. `ring_drop` removes count oldest bytes with count at most size. Helpers support wraparound; only the logical contents and size are observable, and unused storage and the representation of an empty head are unspecified.
|
|
R04. `stream_init(value,port)` makes an unopened stream with both queues empty and all counters, flags, generation, and last_error zero, retaining the supplied port callbacks and context. Initialization does not invoke callbacks. Counters fit in their declared integer types for all supplied journals.
|
|
R05. `stream_open` returns BUSY without mutation if already open. Otherwise it clears both queues, read_end, write_end, last_error, accepted, received, delivered; sets opened to one; increments generation; and returns OK. `stream_close` returns CLOSED without mutation when unopened; otherwise it performs the same clearing, sets opened to zero, preserves generation and port, and returns OK. Neither operation calls the port.
|
|
R06. `stream_queue` returns INVALID if count exceeds 64, then CLOSED if unopened or write_end, then FULL if insufficient outgoing space. Otherwise it appends all count bytes and returns OK. Errors do not mutate state. A valid zero count succeeds on an open writable stream even when its outgoing queue is full.
|
|
R07. `stream_take` first sets taken to zero. It returns INVALID if count exceeds 64, then CLOSED if unopened. Otherwise it copies and removes min(count,incoming.size) oldest bytes, adds that number to delivered, sets taken to that number, and returns OK. It remains usable after read_end. It performs no callbacks.
|
|
R08. `stream_transmit` first sets progress to zero. It returns INVALID if quota exceeds 64, then CLOSED if unopened or write_end. Otherwise it repeatedly requests min(quota-progress,outgoing.size) bytes from the oldest outgoing bytes until quota is met or the queue is empty, then returns OK. Every send callback receives MSG_NOSIGNAL as its flags argument. A zero quota performs no callbacks.
|
|
R09. A positive send result n removes n bytes, adds n to accepted and progress, and continues with the remaining quota and queue. A zero send result returns WAIT. A negative result with errno EINTR repeats the pending request; EAGAIN returns WAIT. Any other negative result stores errno in last_error, sets write_end, and returns FAULT. Every stop retains bytes that the port has not accepted, and progress includes earlier positive results in that invocation.
|
|
R10. `stream_receive` first sets progress to zero. It returns INVALID if quota exceeds 64, then CLOSED if unopened, then END if read_end. Otherwise it repeatedly requests min(quota-progress,incoming free space) bytes using flags zero. It returns FULL without a callback if more quota remains but no space remains, and OK when the quota is met. A zero quota on an open stream without read_end returns OK without callbacks.
|
|
R11. A positive receive result n appends those n bytes and adds n to received and progress before continuing. Zero sets read_end and returns END while preserving write_end and both queues. A negative result with errno EINTR repeats the pending request; EAGAIN returns WAIT. Any other negative result stores errno, sets read_end, and returns FAULT. Prior received bytes and progress survive every stop, and receiving remains available after write_end.
|
|
R12. `stream_finish` returns CLOSED if unopened or write_end, then BUSY if outgoing bytes remain, without callbacks. Otherwise it calls shutdown_write once. A negative result stores errno in last_error and returns FAULT with write_end unchanged; success sets write_end and returns OK. Incoming state is preserved. Repeated finish after success returns CLOSED without a callback.
|
|
R13. A successful operation, WAIT, END, FULL, BUSY, CLOSED, or INVALID does not clear a previous last_error. Only init, successful open, and successful close clear it. accepted counts only bytes accepted by send; received counts bytes returned by receive; delivered counts bytes removed by take. Within a connection received equals delivered plus incoming.size. End flags do not discard queued data.
|
|
R14. Port callbacks return a positive count no greater than the requested count, zero, or -1 with errno set. Valid callback errors are EINTR, EAGAIN, EPIPE, and EIO. Runs have finitely many consecutive EINTR results, and requests are never zero. Callbacks may inspect the complete request. Library calls do not use any other I/O or global signal disposition.
|