docs: correct stale generator, ownership, and overflow-semantics references#2385
Merged
Conversation
All Hew concurrency (generator yield, actor await, and scope-join await) is unified on the LLVM llvm.coro switched-resume continuation substrate (hew-runtime/src/cont.rs). Several comments and one spec section still described the deleted thread-based generator runtime or a nonexistent hew-runtime/src/coro.rs stackful-coroutine layer: - hew-mir/src/state_clone.rs: the Generator IoHandleKind doc referenced a dead hew_gen_free / HewGenCtx symbol pair and a generator-thread join; restated around the real hew_gen_coro_destroy teardown path. - hew-mir/tests/lowering_expr/gen_block_mir_lowering.rs: capture-safety test comments described flat-copying captures across a generator thread boundary and referenced the dead hew_gen_ctx_create symbol; restated around the generator's heap env block. - hew-codegen-rs/src/llvm.rs: removed a stale doc comment asserting a Yield-lowering test calls hew_gen_yield (the test asserts the opposite), and reworded an Option-tag comment that cited a prior thread-runtime path instead of the enum-layout convention it matches. - hew-codegen-rs/tests/exec/generator_exec.rs and hew-runtime/tests/generator_stream_regression.rs: reworded assertion messages and module docs that described a thread model preserving generator state, or a leaked context plus thread, in coro terms. - docs/diagrams.md: the runtime architecture diagram still listed coro.rs (stackful coroutines, coro_switch) and generator.rs as L4 source files; both were deleted. Replaced with the current cont.rs and coro_exec.rs, and fixed a table row still citing coro_switch as the cooperative-yield mechanism. - docs/specs/HEW-SPEC-2026.md: the Task<T> substrate notes described a dormant, unexposed coroutine layer in a deleted coro.rs file as an alternative to OS-thread-per-task scheduling. A child's execution is still OS-thread-per-task, but the parent's await of that child already suspends on the same unified coro substrate as generator yield and actor await, not a separate dormant layer.
The matrix carried two contradictory rows for generators on WASM: one marking them WASM-TODO with codegen fail-closing at hew_gen_yield (a symbol that no longer exists), the other marking basic syntax as passing. Both were stale. The wasm32 generator coro-frame teardown fence was removed months ago, and hew-codegen-rs/tests/exec/ wasm_generator_exec.rs proves scalar and fn-typed-parameter gen fn forms construct, yield, and tear down correctly under wasmtime with zero live coroutine frame bytes after drop, confirmed by running that test against this worktree. The doc's tracking issue (#1451) is closed and unrelated to generators. Replaced both rows with one accurate entry and rewrote the WASM generator note to describe the current llvm.coro switched-resume path instead of the retired thread-runtime substrate. The paired wasm-capability-manifest.toml is kept in cardinality lock-step (the hew-capability-gen row-count gate): the two generator [[feature]] entries are merged into one and the header row count is updated.
The spec and language guide both asserted that plain `+`/`-`/`*` wrap
on overflow, the same as `&+`/`&-`/`&*`. This is backwards: plain
integer arithmetic lowers to `IntArithChecked` (`llvm.{s,u}{add,sub,mul}.with.overflow.iN`)
and traps with `TrapKind::IntegerOverflow` (hew-mir/src/lower.rs);
only `&+`/`&-`/`&*` lower to plain `IntAdd`/`IntSub`/`IntMul` and
wrap. `.wrapping_*`/`.checked_*`/`.saturating_*` mirror the same three
policies as callable methods.
Fixed HEW-SPEC-2026.md §12.2's wrapping-arithmetic note and the
language guide's explicit-intent-arithmetic section, which both
described the reverse behaviour.
Several spec sections still described features as unimplemented or deferred after they shipped: - Iterator hierarchy (§2.4): Iterator/IntoIterator + Map/Filter/Take/Skip adapters + terminals shipped (std/builtins.hew, std/iter.hew); the eager per-type helper table (map_int/filter_int/...) is retired. Only DoubleEndedIterator remains absent — narrowed the section to that. - Generic HashMap/HashSet keys (§2.5): any structural-hash-eligible key (scalars, strings, records/enums of hash-eligible leaves) is admitted (169c42c); the real remaining gap is owned Vec/bytes fields and float keys, rejected with a diagnostic. - Package visibility (§3.5): both the private and package boundaries are enforced at every cross-module reference site (E_VISIBILITY_PRIVATE/E_VISIBILITY_PACKAGE), not merely parsed. - Nested supervisors (§5.5): dotted and chained nested-child access (root.sub, root.sub.worker) lowers end-to-end through hew_supervisor_nested_get; this was previously a fail-closed rejection. - Weak<T> (§3.7.7): corrected the rejection mechanism from "rejected at HIR" to "rejected during type-checking as an unknown type" — Weak<T> itself is still unimplemented, only the described mechanism was wrong. - Edition changelog: dropped channels from the deferred-to-next-edition list (shipped, std::channel) and narrowed the Iterator/HashMap entries to match the sections above.
NestedSupervisorAccessorUnsupported is dead code: nested field access (root.sub, chained root.sub.worker) now lowers end-to-end through hew_supervisor_nested_get and check_supervisor_child_accessor_gates' ChildKind::Static arm no longer constructs it. Its doc comment and the into_result fatal-diagnostic-kind list still described it as gating a v0.6-scheduled ABI call. SupervisorPoolChildAccessorUnsupported is still real, but only for the bare (unindexed) sup.pool_child accessor: indexed access (sup.pool_child[i], via hew_supervisor_pool_child_get/_len) is a separate, already-shipped path. The gate's user-facing diagnostic text and doc comments described the bare accessor as pending a v0.6 hew_supervisor_pool_route ABI call rather than permanently rejected by design (no member index to route on). Updated the doc comments in hew-hir/src/diagnostic.rs and hew-hir/src/lower.rs, the emitted diagnostic message text, and the supervisor_child_accessor_gates.rs test module doc (test bodies already asserted the correct behaviour).
- language guide: module-qualified enum patterns in match arms (ParseError::Invalid(msg)) parse and type-check correctly — the parser loop over DoubleColon segments handles this. Replaced the "currently unsupported at parse time" caveat with a working example. - language guide: deleted the "Generics NYI" section. Both listed bugs are fixed — generic constructor calls without turbofish now infer type args from the expected return type (fcdef24, #2307), and concrete-specialised impl-Trait blocks get distinct mangled symbols (08c5a6c, #2270). - README: split the browser-runtime note. A scoped browser runtime for thread-dependent features (channel/select/sleep/supervisor/TCP) is a ratified v0.6.0 goal, but parallel work-stealing is a permanent native-only limitation, not part of that v0.6.0 scope. - HEW-FUTURE.md §2.1: closures with captured environment are implemented for the general case (captured-state, move captures, closure-typed fields, Option-returning closures, one-level closure-captures-closure). Narrowed the section to the real remaining gap: transitive capture through two or more nested scope levels fails with E_HIR CheckerBoundaryViolation.
- docs/v05/ownership.md: rewrote the whole page. It described an early copy-on-write-per-call model (send() = value-equal copy, a P0-P6 build-out roadmap) that predates the shipped model. Current model is single ownership with move-by-default assignment/call/send, an explicit `.clone()`/`clone x` for duplication (wired for string/Vec/HashMap/HashSet/records), and a gated send mechanism (alias-share-by-retain for string/bytes, deep-copy for mutable collections) that is indistinguishable from move at the language level. Reconciled to HEW-SPEC-2026.md §3.1-3.4 and §3.7. - hew-hir/src/diagnostic.rs: the CloneNotYetSupported doc comment still described String/Vec/HashMap/HashSet as lacking a wired copy path in "M-COW P0/P2" phase language; all four are resolved by the checker before this gate fires today. Rewrote it as the fail-closed backstop description it actually is. - language guide: struck the "owned-handle aggregate state lands in v0.5.1" version promise (still on v0.5.6 without it) and the matching hew-cli/src/diagnostic.rs OwnedHandleAggregateExtractionUnsupported message strings; kept the gap itself, which is real. Same fix in HEW-FUTURE.md §1.4's stream-next select-arm entry. - language guide: replaced the TLS "Known gap (v0.5)" block — the BytesTriple ABI mismatch it described is fixed (00f6b14, hew_tls_write_result/hew_tls_read_result take bytes by pointer to a BytesTriple). The real remaining gap (tls.connect not recording a failed handshake in last_error()) is kept. - docs/specs/handle-safety-and-resource-lifetime.md: the `--experimental-handle-safety` flag was never built (0 code occurrences) — #[resource]/#[linear] ship unconditionally. Fixed the regex.Pattern migration-table row (still #[opaque]/manual-free, its own pending migration) and the C ABI test description, and marked §13's stop-the-bleeding rules as historical: their gating issues (#1228, #1251, #1252, #1295, #1399) are all closed.
HEW-FUTURE.md §4.1 and HEW-SPEC-2026.md §10 both cited a `docs/operations/` directory for hew debug/HEW_PPROF/hew-observe/LSP behavioural contracts. That directory was never created (aspirational placeholder, c61ca81); the real files are docs/observe.md, docs/troubleshooting.md, and docs/dev/lsp-editor-setup.md.
- hew-codegen-rs/src/llvm.rs (two spots): the demonitor drop-symbol comments said "actors are not supported on wasm32". Basic actors (spawn/send/receive/ask) run on wasm32 via scheduler_wasm.rs; only link/unlink/monitor/demonitor are OS-thread-dependent and excluded. Narrowed the wording to what's actually unsupported. - hew-types/src/ty.rs: PRIMITIVE_ALIASES's doc comment and the aliases_for accessor both referenced a wirecodec PRIMITIVE_DESCS table fed by a hew-wirecodec crate that has been retired (not in the workspace) and has no remaining callers of aliases_for. Pointed at the current wire-boundary contract (type_descriptor.rs's canonical_string()) instead. - hew-mir/src/state_clone.rs, hew-runtime/src/mailbox.rs, hew-runtime/src/vec.rs: swapped retired ActorRef<T>/Actor<T> example references for the current actor-handle family (LocalPid<T>/ RemotePid<T>/LambdaPid<M,R>). The underlying mechanisms these comments describe (bit-copy classification, envelope drop-glue refcounting, pointer-sized HewVec elements) are unchanged — only the retired type names needed swapping. Dropped the mailbox.rs Weak<ActorRef> parenthetical rather than inventing a pid equivalent, since no current pid type has a Weak form.
…model The 277a4ddc2 coro-substrate sweep fixed the Rust-side generator comments but explicitly left the `.hew` fixture comments untouched. These five still described captures travelling through a runtime "env channel" (`hew_gen_ctx_create`) into a "generator thread" / "body thread", deep- copied and freed with the thread — the pre-cutover thread-runtime model. Generator captures are copied into a single heap env block (`hew_cont_frame_alloc`) read back by the coro-ramp `__hew_gen_body_*` entry; there is no generator thread and no `hew_gen_ctx_create` symbol. Also fixed a second, separate stale reference in hew-mir/src/state_clone.rs (line ~422, distinct from the block 277a4ddc2 already corrected): the IoHandle admission doc still named the retired `hew_gen_free` resource-drop symbol instead of `hew_gen_coro_destroy`.
- thread-backed-handle-leak-invisible-to-detector (row 151): cited a generator's *mut HewGenCtx blocked on a resume channel as an example of a thread-backed handle invisible to leak detectors. Generators no longer own an OS thread — the stackless-coro cutover made suspension a heap coro frame (HewCont/cont.rs), which leaks --atExit CAN see (row 155's extension already flags this). Scoped the oracle methodology to genuinely OS-resource-backed handles and pointed at row 155 for the current generator-teardown oracle. - actor-surface-no-ask-verb 'why' line: dropped the retired ActorRef<T> reference; the mailbox-boundary nominal types are LocalPid<A>/ RemotePid<A>/LambdaPid<M,R>. The dispatch invariant itself (named actors are signature-driven, no caller verb) is unchanged. - reject-ask-revival: scoped the rejection to named-actor (receive fn) call sites. .send() is the real, shipped verb for the generic Pid/ LocalPid<T>/RemotePid<T> trait surface (std/builtins.hew) and for LambdaPid<M,R> lambda-actor handles (5697ea2) — a PR that only touches that surface is not an ask-revival regression.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
I corrected stale documentation, source comments, and LESSONS rows that had drifted from the current implementation. The most important fix is the integer-overflow semantics in the spec and language guide: plain
+/-/*TRAP on overflow, and the&+/&-/&*family is the wrapping opt-out. The docs had this backwards.I also brought the generator/coroutine substrate references up to date (unified on
llvm.coro), corrected actor-surface naming (LocalPid/RemotePid/LambdaPid), fixed the WASM capability matrix, and cleaned up roughly 18 other drifted references across specs, source comments, diagnostics, and test fixtures. No behaviour change.Verification
cargo checkacross hew-hir, hew-cli, hew-codegen-rs, hew-types, hew-mir, hew-runtime: greencargo fmt --check(pre-push hook): passOut of scope