16cd722 | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

16cd722 — Peter John 2026-10-26T10:06:07+05:30

docs: how generics compile (erasure, boxing at edges, dyn traits); results

Files changed (5) hide show

README.md +24 -3
docs/plans/2026-10-25-erased-generics.md +22 -0
plum-checker/src/lib.rs +10 -13
plum-wasm-codegen/src/lib.rs +19 -23
plum-wasm-codegen/tests/codegen_tests.rs +2 -2

README.md CHANGED Viewed

@@ -244,7 +244,28 @@ fun wrap(value: T) -> Bool =
   True
 ```
-Generic types, methods, and free functions are monomorphized: each concrete instantiation used in the program gets its own specialized copy. `List[Int]` and `List(Int)` both parse as generic arguments.
+Generic types, methods, and free functions are type-checked once and erased. `List[Int]` and `List(Int)` both parse as generic arguments. See [How generics compile](#how-generics-compile).
+### How generics compile
+Generics work like TypeScript's: the checker verifies a generic body structurally against its bounds, then the type arguments are erased. There is exactly one compiled copy of every generic type, method, and function, however many instantiations the program uses. `List[Int]` and `List[Str]` run the same code.
+- **Boxing only at generic edges.** Inside a generic, a `T` value is an `anyref`. Reference types (`Str`, classes, enums) pass through for free. A primitive (`Int`, `Float`, `Bool`, `Byte`) is boxed when it crosses into a `T` slot and unboxed when it comes back out, so `List[Int]` pays one small allocation per element. Non-generic code never boxes.
+- **Bounds are required to call methods on `T`.** `fun show(x: T) -> Str = x.toStr()` is rejected; write `T: ToStr`. The bound is what tells the checker the call exists.
+- **Trait names are types.** Every class and enum value carries a type id in its header, and a call through a trait type dispatches on it at runtime.
+```plum
+trait Shape =
+  area() -> Float
+  name() -> Str
+fun totalArea(shapes: List[Shape]) -> Float =
+  shapes.reduce(0.0, |acc, s| acc + s.area())
+```
+`Circle` and `Square` both implement `Shape`, so a `List[Shape]` can hold either and `s.area()` picks the right method per element (see [`plum-examples/traits.plum`](plum-examples/traits.plum)).
+- **Bare generic types need type arguments.** `p: Parcel` is an error when `Parcel` is generic; write `p: Parcel[Int]` (or `Parcel[T]` inside a generic).
 ## Closures
@@ -455,8 +476,8 @@ It's sugar for `obj.map(|v| v.field)` — nothing more than that; chain it as ma
 - **`Str`** (`import std/Str`) — a byte array with a codepoint-aware layer for Unicode correctness: `runeLength`, `runeAt`, `codePointAt`, `codePointToStr`
 - **`Byte`** / **`[]Byte`** (`import std/Byte`) — a scalar unsigned 8-bit value and a fixed-length mutable byte slice
 - **`Buffer`** (`import std/Buffer`) — a growable, mutable byte sequence for building up a `Str`, amortized O(n) writes
-- **`Array[T]`** (`import std/Array`) — a generic, growable array (reference types only)
+- **`Array[T]`** (`import std/Array`) — the compiler-intrinsic generic array that `List` and `Map` are written on
 - **`Map[K: Hashable, V]`** (`import std/Map`) — a real bucketed hash table
-- **`List[T]`** (`import std/List`) — a singly-linked list with `get`/`add`/`set`/`removeAt`/`remove`/`each`/`map`/`reduce`/`sort`/`join`/`chunk`/`partition`
+- **`List[T]`** (`import std/List`) — a growable list built on `Array`, with `get`/`add`/`set`/`removeAt`/`remove`/`each`/`map`/`reduce`/`sort`/`join`/`chunk`/`partition`
 See [`plum-examples/`](plum-examples) for a runnable file per feature above, and [`plum-std/`](plum-std) for the standard library source.

docs/plans/2026-10-25-erased-generics.md CHANGED Viewed

@@ -204,3 +204,25 @@ Checker: deep (nested TApp substitution, per-call method generics), state (bound
 ## Self-review
 Design items 1→T1, 2→T2, 3,5→T3, 4→T4, 6,7→T5, success criteria→T6. There are no placeholders. Each Consumes line matches a Produces line. Tasks are sequential by ruling, and each one leaves both suites green.
+## Results
+Release build, best of 5, milliseconds.
+| Measure | Before (monomorphizing) | After (erased) |
+|---|---|---|
+| Typical program, total | 380-500 | 20-25 (load ~9, check ~7, codegen ~5) |
+| List.plum | 911 | typical range |
+| Largest (oop_visitor, dop_visitor, Http, Os) | n/a | 32-35 |
+| Bool.plum wasm size | 96.3 KB | 22.7 KB |
+| `plum test` std + examples | ~89 s | ~21-28 s |
+Targets (<=100 ms, <96 KB) met.
+### Open follow-ups
+- A generic fn returning a closure is unparseable (`-> fn(Int) -> Int`).
+- A closure capturing a fn-typed param fails with "unknown function 'cb'".
+- A bare `-> Box` return inside Box's own methods leaves `T` unsubstituted.
+- `List` is not its own intrinsic; it is Plum code on top of `Array`.
+- A built-in `Bool` is planned next.

plum-checker/src/lib.rs CHANGED Viewed

@@ -210,7 +210,7 @@ pub fn enumGenericParams(e: &ast::Enum) -> Vec<String> {
     names
 }
-/// Structural type conversion for UN-monomorphized source: `List[Int]` ->
+/// Structural type conversion for original (erased) source: `List[Int]` ->
 /// `TApp`, a single-uppercase-letter name (the grammar's generic parameter
 /// spelling) -> `TParam`.
 pub fn plumTypeFromAstG(ty: &ast::Type) -> PlumType {
@@ -681,7 +681,7 @@ pub struct EnumVariantInfo {
     pub field_names: Vec<String>,
     pub values: Vec<ast::Expr>,
     /// The owning enum's generic parameter names (`[T, E]` for `Try`) —
-    /// empty for a non-generic enum and for monomorphized specializations.
+    /// empty for a non-generic enum and for non-generic uses.
     pub generics: Vec<String>,
 }
 /// Enum variant name -> its info, e.g. `"True" -> { enum_name: "Bool", tag: 1, field_types: [] }`.
@@ -786,10 +786,9 @@ pub fn buildGlobalTables(source: &ast::Source) -> (TypeEnv, MethodEnv, EnumVaria
                         // This is what lets a bare `Int`/`Float` value be used
                         // directly wherever `Number` is expected with no wrapper
                         // syntax — see `unify`'s matching
-                        // primitive-vs-enum arm, and
+                        // primitive-vs-enum arm; codegen
-                        // `monomorphize::wrapPrimitiveAgainstExpected`, which
-                        // does the actual AST rewrite into this variant's
+                        // wraps into this variant's constructor at
-                        // constructor at specific expected-type usage sites.
+                        // expected-type usage sites.
                         (vec![plumTypeFromName(&v.name)], Vec::new())
                     } else if v.fields.is_empty()
                         && e.name != v.name
@@ -948,11 +947,9 @@ fn paramTypeCompareName(pt: &ast::ParamType) -> Option<&str> {
 /// anywhere) is silently SKIPPED rather than an error: those names are still
 /// purely aspirational today, and erroring on them would break every existing
 /// type that names one, for reasons unrelated to whether it actually implements
-/// its REAL trait claims. Runs on the pre-monomorphization source deliberately —
+/// its REAL trait claims. Runs on the original source deliberately —
 /// a generic class's own methods (and a real trait's own declared signatures,
-/// which are never specialized at all) read naturally here, before mangling
+/// which are never instantiated) read naturally here as written.
-/// folds a method's concrete return/param types into new, unrelated-looking
-/// names (`Link[JsonParseError]` -> `Link$JsonParseError`).
 fn checkTraitConformance(source: &ast::Source) -> Vec<CheckError> {
     let mut errors = Vec::new();
     let traits: BTreeMap<&str, &ast::Trait> = source
@@ -1134,7 +1131,7 @@ fn checkBareGenericTypes(source: &ast::Source) -> Vec<CheckError> {
 fn checkSourceInner(source: &ast::Source) -> CheckResult<()> {
     // Generic items are checked once, structurally (`TApp`/`TParam`), on the
-    // ORIGINAL source — no monomorphization.
+    // ORIGINAL source.
     let mut errors: Vec<CheckError> = checkTraitConformance(source);
     errors.extend(checkBareGenericTypes(source));
     let (global_env, methods, enum_variants, enum_params) = buildGlobalTables(source);
@@ -2139,7 +2136,7 @@ fn inferClassCallRaw(
 /// A class construction call (`FantasyBook(title: ..., ...)`) whose name is ALSO a
 /// bare-type enum variant (`enum Book = | FantasyBook`, see `buildGlobalTables`)
 /// infers as the enum it wraps, not the bare class — mirroring the AST-level
-/// desugaring `monomorphize::rewriteExpr` does before codegen (`FantasyBook(...)`
+/// desugaring codegen does (`FantasyBook(...)`
 /// there literally becomes `Book`'s `FantasyBook(FantasyBook(...))` constructor).
 fn bareVariantWrapType(type_name: &str, ctx: &CheckCtx) -> PlumType {
     match ctx.enum_variants.get(type_name) {
@@ -2398,7 +2395,7 @@ pub(crate) fn lookupFieldType(
 /// belonging to the same enum as `enum_name`, for the `?` operator (`Expr::Try`)
 /// — used identically by the checker (`inferExpr`) and codegen (`inferLocalType`
 /// callers), which is why this lives here rather than inline in either. Returns
-/// `None` if `enum_name` isn't (a monomorphized specialization of) `Try`
+/// `None` if `enum_name` isn't (an instantiation of) `Try`
 /// — i.e. has no `Ok`/`Err` pair of variants.
 pub fn tryOperatorVariants<'a>(
     enum_name: &str,

plum-wasm-codegen/src/lib.rs CHANGED Viewed

@@ -194,7 +194,7 @@ impl WasmModule {
         // `call_indirect` against table 0 purely because its PARAMETER TYPE is
         // `fn(...)` (e.g. `List.each(self, cb: fn(T))`) — that method gets compiled
         // (and its `call_indirect` emitted) whenever its owning class is
-        // monomorphized, regardless of whether THIS PARTICULAR program ever
+        // compiled, regardless of whether THIS PARTICULAR program ever
         // actually constructs a real closure literal anywhere to populate
         // `table_elements`. Without an (empty-but-present) table 0 declared, such
         // a module fails wasm validation ("unknown table 0") even though the
@@ -374,7 +374,7 @@ pub struct CompileCtx<'a> {
     pub closure_asts: HashMap<usize, &'a ast::Closure>,
     /// Closure arity -> the erased `call_indirect` function-type index.
     pub closure_call_types: HashMap<ClosureSigKey, u32>,
-    /// Instantiated type of every expression of the (un-monomorphized) source,
+    /// Instantiated type of every expression of the original source,
     /// keyed by expression address — from `plum_checker::typedSource`.
     pub types: HashMap<usize, PlumType>,
     /// Top-level function name -> global index holding its zero-capture "trampoline"
@@ -944,7 +944,7 @@ fn plumTypeToValtype(t: &PlumType) -> ValType {
     }
 }
-/// Type-section indices for every wasm-gc composite type this program's monomorphized
+/// Type-section indices for every wasm-gc composite type this program's
 /// classes/enums/`Str` need. Populated once in `compileSource` from the checker's
 /// global tables.
 #[derive(Clone)]
@@ -974,7 +974,7 @@ pub struct GcTypeRegistry {
     /// alongside `closure_type_idx`, from every `ParamType::Variadic` in the program.
     pub variadic_array_type_idx: HashMap<ValType, u32>,
     /// The single shared `array<anyref>` type index every `Array[T]`
-    /// specialization (`Array$Int`, `Array$Str`, ...) uses regardless of its own
+    /// uses regardless of its own
     /// `T` — see `libs/std/array.plum`'s header comment. `0` (the `Str` slot,
     /// harmlessly never read as such) until/unless the program actually
     /// instantiates `Array` at least once.
@@ -1028,10 +1028,9 @@ fn typeIdOf(r: &GcTypeRegistry, name: &str) -> i32 {
     r.type_ids.get(name).copied().unwrap_or(0)
 }
-/// Whether `name` is `Array` itself or one of its monomorphized specializations
+/// Whether `name` is the `Array` intrinsic — it is backed by one
-/// (`Array$Int`, `Array$List$Pair$Str$Int`, ...) — every such class shares one
 /// physical wasm-gc array type (`GcTypeRegistry::array_type_idx`) instead of
-/// getting its own struct type, and its `init`/`get`/`set`/`length` methods are
+/// a struct type, and its `init`/`get`/`set`/`length` methods are
 /// compiler intrinsics rather than compiled `todo` bodies (see
 /// `compileIntrinsicFnBody`).
 fn isArraySpecialization(name: &str) -> bool {
@@ -1082,8 +1081,8 @@ fn plumTypeToGcValtype(t: &PlumType, registry: &GcTypeRegistry) -> ValType {
             // A field typed as a generic enum (e.g. `Node.next: Link[Node]`)
             // resolves here to the BARE generic name — `plumTypeFromAst`
             // has no representation for type arguments, so it can't know this means
-            // `Link$Int` once monomorphization specializes (and removes the
+            // `Link[Int]` rather than bare `Link` (erased generics keep one
-            // unspecialized) `Link` — same permissive `anyref` fallback as
+            // compiled `Link`) — same permissive `anyref` fallback as
             // `plumTypeToValtype` above, for the same "genuinely unmodeled" reason:
             // `struct.get`/`ref.test`/`ref.cast` all work against `anyref` operands
             // fine, so a field merely being STORED as `anyref` instead of the exact
@@ -1121,7 +1120,7 @@ fn buildGcTypeRegistry(
         EnumSuper(String),
         Variant(String),
         /// The single shared `array<anyref>` type every `Array[T]`
-        /// specialization aliases — see `isArraySpecialization`.
+        /// aliases — see `isArraySpecialization`.
         ArrayRef,
         Tag,
         BoxI64,
@@ -1164,8 +1163,7 @@ fn buildGcTypeRegistry(
         // are ALL represented by the one shared `array<anyref>` type regardless
         // of `T` (see `isArraySpecialization`'s own doc comment) — alias its
         // enum/variant/class names onto that single existing slot instead of
-        // giving it (and every OTHER `Array$...` specialization) its own real
-        // struct type.
+        // giving it its own real struct type.
         if isArraySpecialization(enum_name) {
             let idx = *array_ref_slot.get_or_insert_with(|| {
                 let idx = slots.len() as u32;
@@ -1815,7 +1813,7 @@ fn compileSourceInner(
     // set up right below) — imports must occupy the low end of the function
     // index space for every later `addFunction`'s index arithmetic to stay
     // correct. `plum-checker` has already confirmed every extern fn has no
-    // receiver and no body, so `f.name` alone (no `fnKey` receiver-mangling) is
+    // receiver and no body, so `f.name` alone (no `fnKey` receiver-qualification) is
     // always its unique key.
     let mut func_ids: HashMap<String, u32> = HashMap::new();
     let mut func_sigs: HashMap<String, FuncSig> = HashMap::new();
@@ -1873,8 +1871,8 @@ fn compileSourceInner(
         if !info.field_types.is_empty() {
             continue;
         }
-        // `Array`/`Array$T`'s bare payload-free variant is aliased onto the
+        // `Array`'s bare payload-free variant is aliased onto the
-        // ONE shared `array<anyref>` type every specialization reuses (see
+        // ONE shared `array<anyref>` type (see
         // `buildGcTypeRegistry`'s `isArraySpecialization` handling), not a
         // real struct type — it's never actually instantiated this way
         // (construction goes through the `init`/`push` compiler intrinsics
@@ -1999,16 +1997,15 @@ fn compileSourceInner(
         .collect();
     // ---- Discovery pre-pass: find every closure literal in every function body. ----
-    // (Runs on the monomorphized source, so any generic types in a closure's context
-    // are already concrete.) Registers each closure as its own wasm function + table
+    // (Runs on the original, erased source.) Registers each closure as its own wasm function + table
     // element and records the free variables it must capture.
     // Only genuine free functions (`type_param.is_none()`) — a bare `FnCall`
     // (`each(...)`) can only ever resolve to a free function, never a method
     // (those always dispatch through `Attribute`/`AttrKind::Method`, keyed by
     // `(receiver, name)` instead — see that arm's own comment below). Keying
     // this by bare name across free functions AND methods would let a
-    // monomorphized method silently SHADOW a same-named free function here
+    // method silently SHADOW a same-named free function here
-    // (e.g. a user's own top-level `each` losing to `List$Str.each` once
+    // (e.g. a user's own top-level `each` losing to `List.each` once
     // `List` happens to be in scope) — same-named methods on unrelated
     // classes are already ambiguous by bare name, so methods have no business
     // being in a bare-name lookup table at all.
@@ -3022,11 +3019,10 @@ fn unwrapStrToBytes(body: &mut Vec<u8>) {
     .encode(body);
 }
-/// `Array[T]`'s `init`/`get`/`set`/`length` — every specialization (`Array$Int`,
+/// `Array[T]`'s `init`/`get`/`set`/`length` — the intrinsic is backed by ONE wasm-gc `array<anyref>` type
-/// `Array$List$Pair$Str$Int`, ...) shares ONE wasm-gc `array<anyref>` type
 /// (`GcTypeRegistry::array_type_idx`, see `isArraySpecialization`), so these
-/// compile identically regardless of which concrete `T` this specialization is
+/// compile identically regardless of the concrete `T`.
-/// for. Every `type_param`-bearing `Fn` — methods AND non-`self` nested
+/// Every `type_param`-bearing `Fn` — methods AND non-`self` nested
 /// "static" constructors like `init` (see `fnWasmParamTypes`) — gets an
 /// implicit receiver as wasm param 0, so a declared plum param at position `k`
 /// is always wasm local `k + 1`. `get` is the one case that also needs a

plum-wasm-codegen/tests/codegen_tests.rs CHANGED Viewed

@@ -1413,7 +1413,7 @@ fun main() -> Int =
 // OPEN: a tag's payload sub-pattern may only be a name or `_` (codegen rejects
 // "unsupported pattern inside tag 'Wrap' payload"), and with a generic enum as the
 // payload (`Wrap(Try[..])`) it currently panics earlier ("'Ok' missing from the GC
-// type registry") because monomorphize never specializes a tag-payload type.
+// type registry") (historical note: written when a monomorphizer existed; generics are now erased).
 #[test]
 #[ignore = "constructor sub-pattern inside a tag payload is unsupported (panics 'Ok' missing from the GC type registry)"]
 fn probe_three_level_nested_tag_pattern_generic_payload() {
@@ -1442,7 +1442,7 @@ fun main() -> Int =
 }
 #[test]
-fn probe_nested_generic_mangled_name_roundtrip() {
+fn probe_nested_generic_name_roundtrip() {
     let got = runTryMain(
         "\
 enum Box[T] =