Hojun-Cho/ww
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

lib: complete the parallel vstream surface to Hare value-return shape (#94 fold-eFinal prep)

Browse Source 
The #94 Option-C vstream surface was left incomplete and structurally
divergent from Hare: constructors heap-allocated and returned (X | nomem)
or used out-params instead of Hare's by-value stack ownership; memio lacked
reset/buffer/borrowedread; bufio's scanner was never ported to the vtable.
This is the additive half of the eFinal collapse — OLD surface stays fully
live; the destructive FLIP (delete OLD + drop _v + repoint) is the next
commit.

Reshape all constructors to VALUE-RETURN (field-by-field sret; the heap +
nomem was an unnecessary crutch — wide slice-bearing struct return-by-value
is byte-id-proven, cf 925_sret_struct_return_run). memio fixed/dynamic/
dynamicfrom, bufio init, log new now return the struct by value; the nomem
is gone with the alloc that forced it.

memio: unify the per-flavour ctx structs onto one `stream` (vt at offset 0);
collapse fixed_string + dynamic_string into a single string() over the common
header (bare-str return is the ratified rule-9 frombytes carve-out, cited at
the site per ref/hare/memio/stream.ha:81); port reset/buffer/borrowedread as
single fns over the header.

bufio: collapse the EXISTING scanner subset (newscannerbuf/scanbyte/scanbytes/
scanline/finish + setflush/flush/unread/isbuffered) onto the vtable, with src
now io.vstream so reads go through io.st_read. The Hare scanner functions ww
never implemented (scanrune/scanstring-arbitrary-delim/readtok/readline/
auto-grow newscanner) are out of scope and deferred to #217 — eFinal is a
collapse, not a feature expansion.

Keep the explicit (&fn): *io.T casts on vtable-slot stores (cgen-neutral;
avoids the #214 (X|void) over-acceptance surface; dropping the casts is a
deferred #206 payoff gated on #214).

Self-gate: 776 (memio) 18/18 and 778 (bufio) 27/27, every row carrying a
cs.s == ww.s byte-id check — bufio/fmt/log are not compiler-embedded, so
these rows are their only byte-id coverage. 779/781 stay STAGE_CS-only
pending #209. Regen w6c+wwdump combined.ww (io+memio are the embedded
modules).
This commit is contained in:
Hojun-Cho
2026-05-29 21:14:39 +09:00
parent f9f83faca7
commit 10cb835f99
10 changed files with 1068 additions and 860 deletions
Download Patch File Download Diff File Expand all files Collapse all files

304
lib/memio/vstream.ww
View File

@@ -1,41 +1,45 @@
// vstream — Hare-shaped vtable wrappers over memio. Project #94
// fold-e2 (Option C, parallel API).
// fold-eFinal(PREP).
//
// Adds three constructors that return `io.vstream` (= `*io.vtable`,
// the Hare-shape from lib/io/stream.ww) alongside the pre-vtable
// memio.fixed / memio.dynamic / memio.dynamicfrom in memio.ww. The
// OLD surface stays untouched here — fold-eFinal (task #50) atomically
// flips the package shape: deletes the OLD constructors + callbacks,
// renames `_vstream` suffix off, and migrates the few callers.
// Adds three constructors that return a memio `stream` BY VALUE (the
// Hare shape, ref/hare/memio/stream.ha:46,58,64) alongside the
// pre-vtable memio.fixed / memio.dynamic / memio.dynamicfrom in
// memio.ww. The OLD surface stays untouched here — fold-eFinal (FLIP)
// atomically flips the package shape: deletes the OLD constructors +
// `state` + callbacks, renames the `_vstream`/`_v` suffix off (so
// `fixed_vstream → fixed`, `stream` stays, `string_v → string`), and
// migrates the few callers (lib/fmt/vstream.ww + the 776 probe).
//
// Hare's memio::fixed/dynamic return `stream` whose FIRST field IS
// `io::stream` (= `*vtable`). ww mirrors that intrusively: each ctx
// struct's first field is `vt: io.vtable` (the vtable embedded
// INLINE, not a pointer to it) so a heap-alloc'd `*fixed_ctx` is
// castable to `vstream = *vtable` via `&c.vt` — and the callbacks
// recover the outer ctx by casting the dispatch arg back to
// `*fixed_ctx`. Same intrusive shape as lib/bufio.stream over
// io.stream (bufio.ww:240-261) and lib/log.stdlogger over logger
// (log.ww:95-98).
// Hare's memio::fixed/dynamic/dynamic_from return a `stream` whose
// FIRST field IS the `io::stream` (= `*vtable`). ww mirrors that
// intrusively: `stream`'s first field is `vt: io.vtable` (the vtable
// embedded INLINE) so a stack `stream` is castable to
// `vstream = *vtable` via `&s.vt` — and the callbacks recover the
// outer `stream` by casting the dispatch arg back to `*stream`. Same
// intrusive shape as lib/bufio + lib/log over their embedded vtables.
//
// Cast workaround per #206: bare `&fn_name` does not type-check as
// a `(*<alias> | void)` field-init / let-binding (the structural
// `*fn(...)` value isn't accepted as the `*reader` named variant
// of the tagged slot). Explicit `(&fn_name): *io.<role>` cast at
// each store site is the Hare-faithful minimum-touch route — same
// workaround test/wcc/775_io_vtable_run.c uses for the bare-vtable
// init. 8 cast tokens here (2 in fixed_vstream + 3 each in
// dynamic_vstream / dynamicfrom_vstream — fixed leaves closer
// void per Hare's fixed_vt, which lets st_close's void-arm return
// plain `void` with no callback needed). Casts drop out wholesale
// once #206 closes.
// VALUE-RETURN (drew, gating): the constructor builds the struct in a
// local `let r: stream;`, field-assigns every slot (including the
// tagged vt sub-fields), and `return r;` — the proven sret round-trip
// shape pinned by test/wcc/925 ("ident_return_rhs" row) and extended
// to tagged-union-field structs by the 776 byte-id rows here. NO heap,
// NO `nomem`: the alloc that forced the OLD `(io.vstream | nomem)`
// return is gone, so the constructor cannot fail. Caller owns the
// returned `stream` (stack ownership, no-GC) and passes `&s.vt` to the
// io.st_* dispatchers — exactly Hare's `&s` into io::write.
//
// Cast workaround per #206-payoff (ken: KEEP the explicit casts; they
// are cgen-neutral and sidestep the #214 over-acceptance surface). The
// `(&fn_name): *io.<role>` cast at each store site is the Hare-faithful
// minimum-touch route — same workaround test/wcc/775_io_vtable_run.c
// uses for the bare-vtable init.
//
// ptr/len/cap kept flat (no `buf: []u8`) per the memio.state note
// (memio.ww:39): chained-dot writes through a state pointer into a
// slice subfield miscompile silently (related to the #195 family);
// the flat shape sidesteps it. dynamicfrom_vstream uses the slice's
// `cap` (NOT `len`) to track the allocated-capacity-to-free on
// close — mirrors the same OLD memio.dynamicfrom note (memio.ww:73).
// slice subfield miscompile silently (#195 family); the flat shape
// sidesteps it. dynamicfrom_vstream uses the slice's `cap` (NOT `len`)
// to track the allocated-capacity-to-free on close — mirrors the OLD
// memio.dynamicfrom note (memio.ww:73).
package memio;
@@ -43,9 +47,13 @@ import io;
import os;
import rt;
// fixed_ctx — heap-alloc'd state for fixed_vstream. `vt` at offset 0
// for the intrusive vstream cast.
export type fixed_ctx = struct {
// stream — Hare's memio::stream (ref/hare/memio/stream.ha:18). `vt` at
// offset 0 for the intrusive stream→vstream cast (`&s.vt`) and the
// callbacks' reverse `s: *stream` cast. Unified across fixed/dynamic
// (Hare keeps a single `stream` over per-mode vtable singletons; ww
// wires the per-mode callbacks post-construction instead). ptr/len/cap
// flat per the memio.state note above.
export type stream = struct {
vt: io.vtable,
ptr: *u8,
len: i32,
@@ -53,68 +61,38 @@ export type fixed_ctx = struct {
pos: i32,
};
// dynamic_ctx — heap-alloc'd state for dynamic_vstream /
// dynamicfrom_vstream. Same intrusive shape as fixed_ctx; the
// difference is the vtable wired (writer=dynamicwrite_v,
// closer=dynamicclose_v) and that the buffer can grow via
// dynamicgrow_v on write overflow.
export type dynamic_ctx = struct {
vt: io.vtable,
ptr: *u8,
len: i32,
cap: i32,
pos: i32,
// fixed_vstream — wire a stream over a caller-supplied buffer. Writes
// never grow; they return 0 once `pos` reaches the end of the buffer
// (Hare returns `nomem` here; ww surfaces 0 to mirror the OLD
// memio.fixedwrite divergence — graduating to Hare's `nomem` return
// needs the widen-from-bare-nomem path that #173 blocks).
//
// Mirrors ref/hare/memio/stream.ha:46.
export fn fixed_vstream(buf: []u8) stream = {
let r: stream;
r.vt.reader = (&read_v): *io.reader;
r.vt.writer = (&fixedwrite_v): *io.writer;
r.ptr = buf.ptr;
r.len = buf.len;
r.cap = buf.len;
r.pos = 0;
return r;
};
// fixed_vstream — wire a vstream over a caller-supplied buffer.
// Writes never grow; they return 0 once `pos` reaches the end of
// the buffer (Hare returns `nomem` here; ww surfaces 0 to mirror
// the OLD memio.fixedwrite divergence — graduating to Hare's
// `nomem` return needs the widen-from-bare-nomem path that #173
// blocks, deferred to eFinal).
// dynamic_vstream — wire a stream with no initial buffer. Writes grow
// the backing allocation; [[io.st_close]] frees it.
//
// Mirrors ref/hare/memio/stream.ha:47.
//
// Three steps (vs Hare's single struct literal): alloc with vt
// zero-init (struct-lit `vt = local_vt` silently drops tagged-union
// fields past the first — sibling task; the `let zero` + post-alloc
// chained `c.vt.X = …` field-assigns through the *fixed_ctx pointer
// is the proven-working route, same shape lib/bufio.init uses on
// b.vtable). Field-assign of a TY_PTR/void variant through the
// chained pointer-into-struct is fine here (*fixed_ctx is a plain
// pointer-to-struct, not an aliased pointer; #195's "aliased-ptr
// receiver" carve-out doesn't bite).
export fn fixed_vstream(buf: []u8) (io.vstream | nomem) = {
let zero: io.vtable;
let c: *fixed_ctx = alloc(fixed_ctx{
vt = zero,
ptr = buf.ptr,
len = buf.len,
cap = buf.len,
pos = 0,
})?;
c.vt.reader = (&fixedread_v): *io.reader;
c.vt.writer = (&fixedwrite_v): *io.writer;
return &c.vt;
};
// dynamic_vstream — wire a vstream with no initial buffer. Writes
// grow the backing allocation; [[io.st_close]] frees it.
//
// Mirrors ref/hare/memio/stream.ha:54.
export fn dynamic_vstream() (io.vstream | nomem) = {
let zero: io.vtable;
let c: *dynamic_ctx = alloc(dynamic_ctx{
vt = zero,
ptr = nil,
len = 0,
cap = 0,
pos = 0,
})?;
c.vt.reader = (&dynread_v): *io.reader;
c.vt.writer = (&dynamicwrite_v): *io.writer;
c.vt.closer = (&dynamicclose_v): *io.closer;
return &c.vt;
// Mirrors ref/hare/memio/stream.ha:58.
export fn dynamic_vstream() stream = {
let r: stream;
r.vt.reader = (&read_v): *io.reader;
r.vt.writer = (&dynamicwrite_v): *io.writer;
r.vt.closer = (&dynamicclose_v): *io.closer;
r.ptr = nil;
r.len = 0;
r.cap = 0;
r.pos = 0;
return r;
};
// dynamicfrom_vstream — like [[dynamic_vstream]] but seeded with an
@@ -123,32 +101,27 @@ export fn dynamic_vstream() (io.vstream | nomem) = {
// half-filled append slice with len < cap and using only `buf.len`
// would under-free on close.
//
// Mirrors ref/hare/memio/stream.ha:65.
export fn dynamicfrom_vstream(buf: []u8) (io.vstream | nomem) = {
let zero: io.vtable;
let c: *dynamic_ctx = alloc(dynamic_ctx{
vt = zero,
ptr = buf.ptr,
len = buf.len,
cap = buf.cap,
pos = 0,
})?;
c.vt.reader = (&dynread_v): *io.reader;
c.vt.writer = (&dynamicwrite_v): *io.writer;
c.vt.closer = (&dynamicclose_v): *io.closer;
return &c.vt;
// Mirrors ref/hare/memio/stream.ha:64.
export fn dynamicfrom_vstream(buf: []u8) stream = {
let r: stream;
r.vt.reader = (&read_v): *io.reader;
r.vt.writer = (&dynamicwrite_v): *io.writer;
r.vt.closer = (&dynamicclose_v): *io.closer;
r.ptr = buf.ptr;
r.len = buf.len;
r.cap = buf.cap;
r.pos = 0;
return r;
};
// ---- vtable callbacks ----------------------------------------------------
// fixedread_v / dynread_v — recover the ctx from vstream's
// `*vtable` via the intrusive offset-0 cast. Separate fns (vs
// sharing one readfn) so each cast targets the matching ctx type
// — the Hare-side `s: *stream` cast in ref/hare/memio/stream.ha:103
// has the same shape but only one ctx flavour.
fn fixedread_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
let m: *fixed_ctx = s: *fixed_ctx;
// read_v — recover the stream from the vstream's `*vtable` via the
// intrusive offset-0 cast. Single fn over the common header (Hare's
// single `read` at ref/hare/memio/stream.ha:103); fixed and dynamic
// share it because the read path is buffer-flavour-agnostic.
fn read_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
let m: *stream = s: *stream;
if (m.pos >= m.len) {
let e: io.eof;
return e;
@@ -166,7 +139,7 @@ fn fixedread_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
};
fn fixedwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
let m: *fixed_ctx = s: *fixed_ctx;
let m: *stream = s: *stream;
if (m.pos >= m.len) { return 0: size; };
let space: i32 = m.len - m.pos;
let n: i32 = buf.len;
@@ -180,26 +153,8 @@ fn fixedwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
return n: size;
};
fn dynread_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
let m: *dynamic_ctx = s: *dynamic_ctx;
if (m.pos >= m.len) {
let e: io.eof;
return e;
};
let avail: i32 = m.len - m.pos;
let n: i32 = buf.len;
if (avail < n) { n = avail; };
let i: i32 = 0;
for (i < n) {
buf[i] = m.ptr[m.pos + i];
i += 1;
};
m.pos += n;
return n: size;
};
fn dynamicwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
let m: *dynamic_ctx = s: *dynamic_ctx;
let m: *stream = s: *stream;
let need: i32 = m.pos + buf.len;
if (need > m.cap) { dynamicgrow_v(m, need); };
let i: i32 = 0;
@@ -213,7 +168,7 @@ fn dynamicwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
};
fn dynamicclose_v(s: io.vstream) (void | io.error) = {
let m: *dynamic_ctx = s: *dynamic_ctx;
let m: *stream = s: *stream;
if (m.cap > 0) { os.free(m.ptr: *void, m.cap: u64); };
m.ptr = nil;
m.len = 0;
@@ -226,7 +181,7 @@ fn dynamicclose_v(s: io.vstream) (void | io.error) = {
// 8. Module-prefixed `_v` suffix vs the OLD memio.dynamicgrow keeps
// the cstage flat-TU private-fn scope from colliding (memio.ww:200
// note + task #9).
fn dynamicgrow_v(d: *dynamic_ctx, need: i32) void = {
fn dynamicgrow_v(d: *stream, need: i32) void = {
let newcap: i32 = d.cap;
if (newcap < 8) { newcap = 8; };
for (newcap < need) { newcap *= 2; };
@@ -241,35 +196,62 @@ fn dynamicgrow_v(d: *dynamic_ctx, need: i32) void = {
d.cap = newcap;
};
// fixed_string / dynamic_string — borrowed str view of buf[0..pos] for
// the matching ctx flavour. Project #94 fold-e7 bundles them here as
// direct enablers for fmt.vbsprintf / fmt.vasprintf (drew-approved per
// feedback_refactor_routing_same_class_drops — prereqs, not churn).
// Mirrors OLD memio.string (memio.ww:102) over `*state`; the V-side
// twins key off the intrusive *<flavour>_ctx cast same shape as the
// vtable callbacks (vstream.ww:151,184). Two flavours kept distinct
// (vs one fn over a shared header) so each cast targets the matching
// ctx type — same rationale as the split fixedread_v / dynread_v at
// line 144-148. Unchecked str view per CLAUDE.md rule 9 carve-out
// (utf8.validate at IO source is opt-in, not wrapped per-construction).
// ---- accessors over the common `stream` header -----------------------
//
// Mirrors ref/hare/memio/ops.ha:51 string(s: io::handle) and the
// per-handle dispatch shape. fold-e8 (task #50 prereq) extends with
// buffer/reset/borrowedread accessors; this fold ships only the
// vbsprintf / vasprintf enablers.
// Single fn each (drew string-collapse): Hare's string/reset/buffer/
// borrowedread all take `*stream` and read the flat header, so the
// fixed/dynamic split the OLD V-side carried (fixed_string /
// dynamic_string) collapses to one. FLIP drops the `_v` suffix
// (string_v → string, …) and deletes the OLD `*state` twins in
// memio.ww.
export fn fixed_string(vs: io.vstream) str = {
let c: *fixed_ctx = vs: *fixed_ctx;
// string_v — bytes written so far, as a str view (buf[0..pos]).
//
// Mirrors ref/hare/memio/stream.ha:81 string(in: *stream). Hare returns
// (str | utf8::invalid) — the validating constructor. ww returns a bare
// `str` per the CLAUDE.md rule-9 frombytes carve-out: utf8.validate at
// the IO source is opt-in, never wrapped per-construction; the honest
// name reserves a future validating helper.
export fn string_v(s: *stream) str = {
let r: str;
r.ptr = c.ptr;
r.len = c.pos;
r.ptr = s.ptr;
r.len = s.pos;
return r;
};
export fn dynamic_string(vs: io.vstream) str = {
let c: *dynamic_ctx = vs: *dynamic_ctx;
let r: str;
r.ptr = c.ptr;
r.len = c.pos;
// buffer_v — borrowed []u8 view of bytes written so far (buf[0..pos]).
//
// Mirrors ref/hare/memio/stream.ha:74 buffer(in: *stream).
export fn buffer_v(s: *stream) []u8 = {
let r: []u8;
r.ptr = s.ptr;
r.len = s.pos;
return r;
};
// reset_v — rewind the cursor and truncate the logical content to 0.
// Backing storage is preserved; subsequent writes (dynamic) re-fill
// from the start without reallocation.
//
// Mirrors ref/hare/memio/stream.ha:87 reset(in: *stream).
export fn reset_v(s: *stream) void = {
s.pos = 0;
s.len = 0;
};
// borrowedread_v — return an `amt`-byte view starting at `pos` without
// copying, advancing the cursor. eof if fewer bytes are available.
//
// Mirrors ref/hare/memio/stream.ha:94 borrowedread(st: *stream, amt).
// `amt: i32` (not Hare's `size`) per the i32-index convention.
export fn borrowedread_v(s: *stream, amt: i32) ([]u8 | io.eof) = {
if (s.len - s.pos < amt) {
let e: io.eof;
return e;
};
let r: []u8;
r.ptr = s.ptr + (s.pos: u64);
r.len = amt;
s.pos += amt;
return r;
};