Module prelude

File-level privilege flag for the pragma(...) builtin. Declared at the top of a Yo file (e.g. pragma(Pragma.AllowUnsafe);) to opt the file into compiler-recognized behaviors. See plans/reference/MEMORY_SAFETY.md.

=== Cycle-GC tracing === GcTracer carries the cycle collector's edge-registration callback (an opaque raw pointer). A Trace impl calls tracer.visit(slot) once per outgoing edge, passing a POINTER to where the child lives (a struct field or a container buffer element). The raw callback is never touched directly.

The functions behind an Allocator. Implementing one needs pragma(Pragma.AllowUnsafe).

• alloc(ctx, size) returns a block of at least size bytes aligned to 16, or .None.
• realloc(ctx, ptr, new_size) resizes a block this vtable's alloc returned, keeping its first min(old, new_size) bytes. .None leaves the original block untouched and still owned by the caller.
• free(ctx, ptr) releases such a block.

There is no size at free and no aligned family: every container buffer and every RC block uses the plain family (see std/allocator.yo's module notes).

An allocator value: an opaque context plus an immortal vtable. Two words, copied freely; it is not reference counted, because an allocator must not itself need an allocator.

Half-open range start..end (excludes end).

Inclusive range start..=end (includes end).

Ordering — result of a comparison.

Reverse(T) — a wrapper whose Ord is T's, inverted (Rust's core::cmp::Reverse).

It turns any max-ordered structure into a min-ordered one without a second implementation. PriorityQueue is a MAX-heap (D11), so a min-heap is:

pq := PriorityQueue(Reverse(i32)).new();
pq.push(Reverse(i32)(i32(5)));
pq.push(Reverse(i32)(i32(1)));
pq.pop().unwrap().value;  // 1 — the SMALLEST

It is equally the way to sort descending: list.sort_by((a, b) -> (Reverse(i32)(a) < Reverse(i32)(b))).

RawSlice — a plain ptr+len pair for PRIVILEGED (pragma'd) code: C interop and std internals. Carries a raw pointer, so the existing raw-pointer gates apply: safe code cannot name or construct it. Replaces the builtin Slice(T) for internal plumbing (plans/archive/SLICE_REWORK.md step 4).

ComptimeValue — a data document read at COMPILE time (plans/archive/BUILD_AND_DEPENDENCY_SYSTEM_REDESIGN.md §5.2).

comptime_json_parse and comptime_toml_parse return one of these. No runtime container can exist at compile time, so the tree is built from ComptimeList and comptime scalars only.

A table keeps PARALLEL key and value lists, the shape std/encoding/json's JsonValue.Object and std/encoding/toml's TomlValue.Table already use. The plan sketched a separate ComptimeEntry struct instead; that shape is not expressible, because ComptimeEntry.value : ComptimeValue and ComptimeValue.Table(… ComptimeEntry) are mutually recursive TYPE definitions and the evaluator rejects those ("cyclic definition"). Parallel lists need only Self, which is fine. Keys are in document order.

ExprList

Type reflection metadata structs — used by Type.get_info(). StructKind — discriminant for struct flavors.

TypeFieldInfo — metadata for a single struct/object field.

TraitInfo — lightweight reference to a trait type.

TraitFieldInfo — metadata for a single trait field.

ParamInfo — metadata for a function parameter.

ForallParamInfo — metadata for a generic type parameter.

ImplicitParamInfo — metadata for a using/effect parameter.

FunctionInfo — metadata for a function type.

TraitKind — discriminant for different trait flavors.

VariantInfo — metadata for an enum variant.

TypeInfo — compile-time enum representing rich type metadata. Returned by Type.get_info() for compile-time type reflection.

FieldInfo — compile-time struct field metadata for derive rules (legacy alias).

Option — a value that may or may not be present.

Option(T) has two variants:

• .Some(value) — contains a value of type T
• .None — contains no value

Example

(x : Option(i32)) = .Some(i32(42));
assert(x.is_some(), "expected Some");
assert(x.unwrap() == i32(42), "expected 42");

DeriveContext — context passed to derive rule functions (needs Option). Used by the derive macro to generate trait implementations.

Result — a value that is either success (Ok) or failure (Err).

Result(OkType, ErrorType) has two variants:

• .Ok(value) — contains a success value of type OkType
• .Err(error) — contains an error value of type ErrorType

Example

(r : Result(i32, str)) = .Ok(i32(42));
assert(r.is_ok(), "expected Ok");

Box(V): the old spelling of the shared, reference-counted cell, now Rc(V) (plans/VALUES_BY_DEFAULT.md §6 V1 step 1). Nothing in std, src or tests spells it. It stays defined for ONE seed only: the v0.2.54 seed compiles src/ against this std and still synthesizes box(...) when dyn(...) auto-boxes a payload that is not an object. Generation B part 2 deletes Box/box once SEED_VERSION carries Rc as the canonical cell, and V1 step 2 later reintroduces Box as the unique, uncounted cell.

Rc — a heap-allocated, reference-counted cell for a single value: the shared, counted cell's name under plans/VALUES_BY_DEFAULT.md (§3.2, decision 1). Copying a handle shares one heap value and bumps its count, as with Rust's Rc<T>; w.* names the payload, and w.field / w.method() reach it through auto-dereference (Deref).

Rc(V) is the canonical shared cell (V1 step 1, Generation B): the cell the compiler synthesizes (dyn(v) auto-boxes into rc(v)), and the one every std, src and test site spells. The legacy Box(V) above is a separate type with the same definition, kept for the seed only.

a := rc(i32(42));
b := a;          // a second handle to the same value
consume(b.* = i32(7));
assert(a.* == i32(7), "a and b name the same value");

=== Arc === Arc — an atomically reference-counted, thread-safe container for a single value.

Use arc(value) to allocate. Access the inner value with a.*.

Example

a := arc(i32(42));
assert(a.* == i32(42), "inner value is 42");

MaybeUninit — a wrapper that allows holding an uninitialized value.

Useful for FFI or low-level patterns where a value must be allocated first and initialized later (e.g., by a C function). assume_init takes the as_ptr() result as a witness — a pointer only unsafe-capable code can hold — so safe code cannot read the uninitialized slot (issues/fixed/safe-code-reads-uninitialized-memory-through-maybeuninit-assume-init.md).

Example

extern(
  "C",
  time_t : Type,
  time : (fn(timer : ?*time_t) -> time_t)
);

uninitialized_timer := MaybeUninit(time_t).new();
ptr := uninitialized_timer.as_ptr();
time(.Some(ptr));
timer := uninitialized_timer.assume_init(ptr);

IterPair — a two-element product type used by enumerate and zip.

Lazy iterator that maps each element through a function F.

Created by calling .map(f) on any iterator. I is the source iterator type, B is the output element type, F is the mapper closure type satisfying Fn(item : A) -> B.

Lazy iterator that skips elements for which the predicate returns false.

Created by calling .filter(pred) on any iterator. I is the source iterator type, F is the predicate closure type satisfying Fn(item : A) -> bool — by value, symmetric with map (plans/archive/STD_API_AUDIT.md D3.4's callback-asymmetry fix).

Lazy iterator that yields at most n elements from the source.

Created by calling .take(n) on any iterator.

Lazy iterator that skips the first n elements of the source, then yields all remaining elements.

Created by calling .skip(n) on any iterator.

Lazy iterator that pairs each element with its zero-based index.

Created by calling .enumerate() on any iterator. Yields IterPair(usize, A) values where _0 is the index and _1 is the original element.

Lazy iterator that combines two iterators element-by-element into pairs. Stops as soon as either iterator is exhausted.

Created by calling .zip(other) on any iterator. Yields IterPair(A, B) values.

Lazy iterator that yields all of the first iterator, then all of the second.

Created by calling .chain(other) on any iterator. Both iterators must yield the same Item type.

Lazy iterator that yields elements while pred holds, then stops forever.

Created by calling .take_while(pred) on any iterator.

Lazy iterator that skips elements while pred holds, then yields the rest.

Created by calling .skip_while(pred) on any iterator.

Lazy iterator that maps each element to an Option and yields the Somes.

Created by calling .filter_map(f) on any iterator. B is the output element type, F satisfies Fn(item : A) -> Option(B).

Iterator wrapper that can look at the next element without consuming it.

Created by calling .peekable() on any iterator. A is the element type.

Lazy iterator that yields the source's elements back-to-front.

Created by calling .rev() on any DoubleEndedIterator. next pulls from the source's BACK and next_back from its FRONT, so .rev().rev() restores the original order.

FutureState — the state of an async Future.

JoinHandle — a handle to a spawned async task. Generic over T, the return type of the spawned task.

The handle OWNS a reference to the task's future: the task (and its result) stay alive for as long as some copy of the handle does, and dropping the last copy releases it. A handle that is dropped without being awaited DETACHES the task — it keeps running and frees itself when it finishes — which is what makes a fire-and-forget io.spawn(…) statement correct (it used to leak the whole state machine, issues/fixed/statement-level-io-spawn-leaks-the-state-machine.md). Awaiting does not consume the handle; awaiting it twice reads the same result.

Io module — the async runtime effect.

Provides io.async, io.await, io.spawn, and io.state operations. Automatically injected into main when declared with io : Io.

Comptime trait — indicates a type that can be used at compile-time. Examples: i32, bool, Type, comptime_int, comptime_float, comptime_str. Non-examples: int, ushort (runtime-only types).

Runtime trait — indicates a type that can be used at runtime. Examples: i32, bool, *(i32), void. Non-examples: comptime_int, comptime_float, comptime_str, Type (compile-time-only types).

Send trait — a value of this type may be MOVED to another thread.

The compiler derives it (plans/VALUES_BY_DEFAULT.md §3.8): a value is Send iff it reaches no non-atomic reference cell (Rc, Box, a ref(struct(...))), every component is Send, and it holds no raw pointer and no borrow. An atomic object is Send iff it is Sync, because its copies share one payload. Raw pointers are neither Send nor Sync unless a type opts in, with impl(T, Send()) under pragma(Pragma.AllowUnsafe).

Sync trait — copies of a value of this type may be READ from several threads at once.

Derived like Send, over shared reads instead of a move: plain data, atomic cells (Arc, Atomic*, Mutex) and values composed of them are Sync; a non-atomic reference cell is not, and neither is a raw pointer unless a type opts in with impl(T, Sync()) under pragma(Pragma.AllowUnsafe). A closure is Sync iff its captured state is. Dyn(Trait) is Sync only as Dyn(Trait, Sync).

Acyclic trait - indicates a type that cannot form reference cycles. Types that implement Acyclic don't need cycle collection tracking. Primitive types, value types without object fields, and objects that don't reference back to themselves (directly or indirectly) are Acyclic.

MoveOnly trait - a value that cannot be copied, only moved.

A value type is move-only when it implements Dispose, when it declares impl(T, MoveOnly()), or when one of its fields, variant payloads, tuple or array elements, or closure captures is move-only. The compiler derives it; a declaration is needed only for a type that has no Dispose but must still never be duplicated (a token, a unique id).

A copy of a move-only value is a compile error (E0901). y := x moves x, and so do passing it to an own(...) parameter, storing it in a field or element, returning it and capturing it in a closure. A by-value parameter borrows it, so use_file(f) needs no move. Only a value type (struct, enum, newtype, and the tuples, arrays and closures built from them) can be move-only. A reference type (ref(struct(...)), Rc, Arc) is how a value is shared: its copies alias one cell, so it is never move-only, even around a move-only payload.

Dropping the last copy of the handle releases the task's future.

Trace trait — mandatory for every reference type that can transitively hold a managed reference. Auto-derived by the compiler for structs/enums (incl. Option and all value types); hand-implemented for containers whose elements live in a heap buffer (ArrayList, HashMap, …). The constructor wires header.traverse_fn to this trace. Like Dispose, only a reference type may implement it (checked at the impl).

Index trait — enables container(idx) subscript syntax at runtime. The Idx parameter is the index type (e.g., usize, Range(usize)). Implementations must define an Output associated type and an index method.

IndexUnchecked — the bounds-check-free twin of Index(usize). Codegen calls index_unchecked instead of index ONLY at a subscript the verifier proved in bounds, in a verify-mode file (plans/backlog/SAFE_MODE_5B_CONTAINER_BOUNDS_ELISION.md). It returns a raw pointer, so safe code cannot call it. An impl's body must be its index body minus the length test: anything weaker turns a proof into undefined behavior.

ComptimeIndex — compile-time indexing trait for constant expressions.

RangeOp trait — enables start..end operator syntax.

RangeInclusiveOp trait — enables start..=end operator syntax.

Add trait — enables lhs + rhs operator. Parameterized by Rhs type.

Compile-time variant of Add.

Sub trait — enables lhs - rhs operator.

Mul trait — enables lhs * rhs operator.

Div trait — enables lhs / rhs operator.

Mod trait — enables lhs % rhs operator.

BitLeftShift trait — enables lhs << rhs operator.

BitRightShift trait — enables lhs >> rhs operator.

Negate trait — enables unary -value operator.

LogicalNot trait — enables !value boolean negation.

BitNot trait — enables ~value bitwise complement.

BitAnd trait — enables lhs & rhs bitwise AND.