Skip to main content

class_static_instance

Function class_static_instance 

Source
pub fn class_static_instance(
    class_template: ClassTemplateId,
) -> (InstanceId, TemplateKey)
Expand description

Classes plan Task 4 (docs/superpowers/plans/2026-10-03-classes.md, LRM 8.9): the (InstanceId, TemplateKey) pair [StateEngine:: allocate_class_static_singletons] uses for one ClassTemplateId’s static-property singleton segment — a deterministic, pure function of class_template alone (never re-derived differently by two call sites), so every caller (that one allocate_instance call, and every later foreign-slot reference a Class::static_prop/obj.static_prop access mints) agrees on exactly which synthetic instance a given class template’s statics live in.

Not defined in netlist:: despite otherwise matching crate::netlist::ClassTemplateId’s own “frontend-independent, needed by STATE” placement rationale: netlist_dedup_invariants.rs’s NL-018 guard (codegen_never_needs_a_second_dedup_key_derivation) source-scans exactly five netlist:: files for any function whose signature returns a TemplateKey, asserting the only name that ever does is dedup_key — protecting that module’s own monopoly on a REAL elaborated module instance’s dedup key. This function mints a key for a wholly different, synthetic thing (a class-static singleton has no Definition/dedup identity of its own), the same way vj::run’s own package/bank synthetic TemplateKeys are minted inline there, outside netlist:: entirely, rather than through a second netlist:: function — this one lives next to its one real caller for the identical reason.

Reserved id-range convention, matching the one vj::run already established for its own synthetic instances rather than inventing a second one: a real elaborated InstanceId is bump-allocated from 0; a design’s packages each get one counting DOWN from u32::MAX; the net-resolution “bank” reserves the single id u32::MAX - (1 << 20). Class-static segments reserve the next block down again, counting from u32::MAX - (2 << 20) — disjoint from both of those by the same generous-headroom convention (not a mathematically tight partition: no real design instantiates anywhere near 2^20 packages, let alone that many packages and that many distinct class templates with static properties at once), so a TemplateKey.definition minted here can never collide with one a real module Definition, a package, or the bank ever uses.

Panics (rather than silently wrapping into collision) if class_template’s own dense id would exhaust that reserved block — expect-style, never a wrapping/saturating fallback, because a wrapped id would silently alias a different class template’s segment: exactly the “gate that can never fail” this plan’s own correctness posture forbids. 2^20 class templates with static properties is not a real design this implementation supports; it is a defensive bound stated loudly rather than left to wrap.