<img align="right" src="../../images/sleela/sleela-medium-profile-permanent-icon-002.jpg" width="45" height="45" alt="SLeeLa">
POINTERS — object references in SLeeLa
Every object has two tiers. Tier 1 is the ordinary object-oriented public interface. Tier 2 is the whole, complete model of the same object as the VM, the memory manager, the operating system and the separation boundary see it. The implicit member
target.refis the bridge between them.
< tier 1: the object, as the class declares it >
Target target = new Target("suppose");
< tier 2: its VM-level reference >
int p = target.ref;
< and the typed way back >
Target again = Target.deref(p);
Status: implemented (first slice). Runnable reference:
examples/pointers-demo.sleela. Regression
tests: impl/tests/refs/ (make test-ref). This document
describes what the current build actually does; the Not yet section lists what
it does not.
1. The idea in one page
C and C++ let you hold a pointer to an object: compare it, test it, store it,
follow it back. SLeeLa never shows a raw machine address — its documented rule is
that "a Sleela program never sees a raw pointer" — but it already represents an
object as a small VM-local handle. .ref makes that handle a first-class,
safe, inspectable value.
| You want (C / C++) | In SLeeLa | Notes |
|---|---|---|
&obj — address of | obj.ref | an int; 0 is the null ref |
*p — follow it | Class.deref(p) | the object, or null — never a crash |
p == q — same object | p == q | refs are ints; equal refs name one incarnation |
p == nullptr | p == 0 | null.ref is 0 |
weak_ptr::expired() | !Ptr.valid(p) | |
weak_ptr::lock() | Class.deref(p) | null when expired |
| dangling pointer (UB) | stale ref | detected, reads as invalid |
sizeof(*p), typeid | Ptr.bytes(p), Ptr.type(p) | tier-2 views |
| pointer arithmetic over memory | not supported | see §5 |
reinterpret_cast, raw bytes | not possible | by design |
So it is closest to a std::weak_ptr with a generation-checked slot, not to
a raw T*: you can play with it like a pointer, but it can never corrupt memory
or alias the wrong object.
2. Tier 1 — the OOD public interface
This is the object as the class describes it. It is what ordinary SLeeLa code sees, and it is unchanged by this feature.
| Aspect | What tier 1 contains |
|---|---|
| Type | A class name. Nominal and static: Target. Single inheritance (syntax ≥ 1.10), base fields placed first. |
| State | The declared instance fields, in declaration order (base class first). Fields start null; field initializers run at construction. Static fields are separate class-level globals (Class::field). |
| Behaviour | The declared methods. A call binds statically by the receiver's declared class name (Target::getLabel); the object is passed as a hidden first argument (this). There is no vtable and no runtime dispatch on the object's actual class. Inherited methods are aliased onto the derived class unless overridden. |
| Construction | new Target("suppose") zero-initialises the fields, runs the initializers, then calls the constructor. Constructor arguments exist since syntax 1.8, with one constructor per class (no overloading, no this(...)/super(...) delegation). |
| Identity | == compares identity. Assignment aliases (Target b = a; is the same object). |
| Access | obj.field, obj.method(...); protected methods are checked; static methods are called through the class. |
| Lifetime | Reachability only. There is no destructor and no reference count; the collector reclaims what is unreachable. |
| Visible limits | 64 fields per class, 4,096 live objects per VM, 65,536 distinct class/struct layouts. |
| Casts | OP_CHECKCAST / OP_INSTANCEOF compare the runtime layout (with its parent chain) against a class. |
What tier 1 hides: where the object lives, which incarnation of its slot it is, how big it is, how old it is to the collector, and how the system accounts for it. That is tier 2.
3. Tier 2 — the complete model
Tier 2 is everything about the same object that is not in the class
declaration. It is read through target.ref and the Ptr namespace. It has four
lenses, matching the four things that "refer to" an object below the language.
Measured on this build (impl/core/sleela_core.c, 64-bit Linux):
| Quantity | Value |
|---|---|
sizeof(SLValue) | 32 bytes (16-byte aligned, because of its 128-bit integer member) |
sizeof(SLStructInstance) — one object | 2,080 bytes |
header (active, type) | 16 bytes |
fields[64] | 64 × 32 = 2,048 bytes, at offset 16 |
gc_object pointer | offset 2,064 |
generation (31-bit incarnation counter) | offset 2,072 — fits existing padding, no size cost |
sizeof(SLGCObject) — the collector's record | 56 bytes |
| Instance store | SL_MAX_STRUCTS (4,096) × 2,080 = 8,519,680 bytes, allocated lazily |
3.1 The VM lens
How the virtual machine represents the object.
| Item | Detail |
|---|---|
| Value | A tagged value { type = SL_STRUCT, h = <int32 slot> }. The slot is an index into the VM's instance store, not an address. |
| Instance record | SLStructInstance { active, type, fields[64] of SLValue, gc_object, generation }. Field storage is dense; a field's offset is its declaration index. |
| Layout | One entry per class/struct in the layout table: SLStructType { name, nfields, parent_type, field names }. Registered by slvm_declare_struct; the single-inheritance link is parent_type. An instance's type is its layout index. |
| Opcodes | OP_NEWSTRUCT (allocate), OP_GETFIELD / OP_SETFIELD (checked, with a GC write barrier on set), OP_CHECKCAST, OP_INSTANCEOF, OP_CALL (the receiver is argument 0), and — new — OP_REF. |
| Slot validity | A slot is valid when it is in range and active. |
| Concurrency | The store is guarded by struct_mtx. |
| Read with | Ptr.id(p) (slot), Ptr.type(p) (layout index), Ptr.fields(p) (field slots), Ptr.gen(p) (incarnation), Ptr.valid(p). |
3.2 The memory-manager lens
How the collector and the accounting treat the object. There are two separate systems, and it matters which one an object belongs to.
| System | Does an object belong to it? | Detail |
|---|---|---|
The garbage collector (runtime/garbage_collector.*) | Yes | A tracing, generational, incremental mark-sweep collector. Every object is an SLGCObject with payload, bytes, marked, queued, remembered, age, external, generation (young/old), mark_children, destroy. Objects are reachability-managed; there is no reference count. A write barrier and a remembered set handle old→young stores. Collection runs at VM safepoints, and only while no worker threads are active. |
The accounting allocator (impl/core/sleela_memmgr.*, the [memory-manager] report) | No | A process-wide counter with a hard limit that backs the [memory-manager] live=… live-allocs=… lines. Language objects do not pass through it, so those counters do not move when you create objects. Per-object accounting would be new work. |
| Item | Detail |
|---|---|
| Size | Ptr.bytes(p) — the payload registered with the collector (2,080 for any class instance). |
| Age / generation | Ptr.age(p) counts collections survived; Ptr.old(p) is true once promoted to the old generation. |
| VM-wide | Ptr.live() = active instances; Ptr.limit() = the 4,096 ceiling. |
| Lifecycle | Allocated white; marked from roots (globals, constants, the operand stack, thread stacks); unmarked objects are swept, which clears the slot and bumps its generation. |
3.3 The operating-system lens
What the host operating system sees of the object: very little, deliberately.
- There is no OS-visible address, handle or descriptor for an individual object. To the OS the whole VM is one process.
- Objects live inside one contiguous instance store — a single zero-initialised allocation of 8,519,680 bytes made on the first object allocation. The OS sees that one block, not 4,096 objects.
- Objects are therefore not counted by the process-level accounting allocator (see §3.2). There is no per-object mapping, pinning, or sharing with other processes; the store as a whole is an ordinary heap allocation that the C allocator and the OS may back however they like.
- Anything that does have an OS identity — sockets, files, spawned processes, threads — is a separate VM-local bounded handle table with its own opcodes, not an object.
Ptr exposes nothing here because there is nothing here to expose. This is a
safety property, not a gap: it is why a ref cannot be used to read or write
memory.
3.4 The separation lens
What keeps the two tiers, and different VMs, apart.
| Boundary | How it is kept |
|---|---|
| Tier 1 ↔ tier 2 | Tier 1 code cannot see a slot or a generation. The only door is .ref (one opcode), and it hands out an opaque, validated int. |
| Ref ↔ memory | A ref is never an address. It selects a slot in a bounded table and is re-validated on every use: slot in range, slot active, generation equal. |
| Object ↔ object | Class.deref also checks the target is an instance of Class; a ref that lands on a different class reads as null. |
| VM ↔ VM / run ↔ run | A ref is meaningful only inside the VM that made it. It is not persisted: the artifact format does not store live objects (a saved struct-typed global reloads as null), and generations restart at 0 in a new run, so a ref written to disk or sent elsewhere must be treated as garbage. |
| Thread ↔ thread | The store is shared and mutex-guarded; collection is deferred while workers run. |
| ISA | Tier 2 is one append-only opcode (OP_REF, 182) with one packed operand, so it cannot grow a back door without an ISA change that the CI gates. |
4. The reference: target.ref
4.1 Format
A ref is an ordinary int:
ref = (generation << 32) | (slot + 1) 0 is the null ref
For the first object in a fresh VM (slot 0, generation 0) the ref is 1.
generation is a 31-bit counter on the slot, incremented every time the
collector reclaims that slot. That is what stops a reused slot from aliasing:
an old ref (slot 1, generation 0) -> (0 << 32) | 2 = 2
the new object (slot 1, generation 1) -> (1 << 32) | 2 = 4294967298 different value
4.2 Semantics
- Weak. A ref does not keep its object alive. It is an
int, not an object value, so the collector does not trace it. - Valid ≠ reachable.
Ptr.valid(p)means "this slot is still occupied by the same incarnation." An unreachable object that has not yet been swept is still valid until the next collection. derefmakes it strong again.Class.deref(p)returns an ordinary object value. If a collection is in its marking phase, the object is shaded first, so a value now on the stack cannot be freed underneath you.- Fails closed. A null, stale, forged, out-of-range or wrong-class ref never traps and never reaches memory:
| Operation on a bad ref | Result |
|---|---|
Class.deref(p) | null |
Ptr.valid(p), Ptr.old(p) | false |
Ptr.id/gen/type/fields/bytes/age(p) | -1 |
Ptr.live(), Ptr.limit() | unaffected (VM-wide) |
- Only misuse of the type is an error.
.refapplied to a non-object, or aPtr.*call given a non-int, is a compile error (or a runtime error if the type is only known late).
5. Language surface
| Form | Type | Meaning |
|---|---|---|
x.ref | int | the ref of object x; 0 when x is null |
Class.deref(p) | Class | the object, or null if p is invalid or not a Class |
Ptr.valid(p) | boolean | slot occupied by the same incarnation |
Ptr.old(p) | boolean | promoted to the old generation |
Ptr.id(p) | int | slot index (-1 if invalid) |
Ptr.gen(p) | int | slot incarnation |
Ptr.type(p) | int | layout (class) index |
Ptr.fields(p) | int | number of field slots in use |
Ptr.bytes(p) | int | instance size as the collector counts it |
Ptr.age(p) | int | collections survived |
Ptr.live() | int | active objects in the VM |
Ptr.limit() | int | object-store ceiling (4,096) |
Rules:
x.refis read-only.x.ref = 5;is rejected: "'ref' is the implicit reference of an object and is read-only."- A declared field named
refwins.refis not a keyword, and 155 existing.sleelalines already use it as an identifier. If a class declares a fieldref,x.refis that field. - A user class, variable or struct named
Ptrwins. The builtin namespace applies only when no such name is in scope (the same rule asMunction). - Not version-gated.
x.refon a class without areffield was already a compile error in every edition, so no previously valid program changes meaning. - Arithmetic on refs is not a supported operation. A ref is an
int, sop + 1compiles, but it only changes a slot number; the result is validated like any other ref (Ptr.valid(p + 1000000)isfalse) and may name some other live object. UsePtr.idto read the slot; do not compute with refs.
Worked example
examples/pointers-demo.sleela prints, for
Target target = new Target("suppose") (output from this build):
== Tier 1: the public interface ==
label = suppose
== Tier 2: the VM view, through target.ref ==
ref (packed handle) : 1
valid : true
slot id : 0
slot generation : 0
layout (type) index : 0
field slots : 1
instance bytes (GC) : 2080
collector age : 0
old generation : false
live objects in VM : 1
object store limit : 4096
== Weak, and never aliased ==
ref to a short-lived object, before collection: slot 1 generation 0
after a full collection, still valid? : false
a new object reuses slot 1 at generation 1
old ref equals new ref? : false
old ref still reaches an object? : false
the surviving object is now old : true
The layout index (0) depends on class order in the program; the rest is
structural.
6. Safety properties
- No raw addresses. A ref indexes a bounded table; there is no way to turn it into a machine address or to read or write outside the table.
- Every use is validated (range, active, generation, and — for
deref— class). - No use-after-free by aliasing. A reclaimed slot's generation moves on, so old refs cannot name the object that reuses it.
- No resurrection hazard.
derefshades the object during incremental marking. - Closed under bad input. NaN, negatives, huge values and
nullall fail closed (§4.2). - Bounded. 4,096 objects, 64 fields, and a 31-bit generation (a slot would have to be reclaimed 2,147,483,648 times to wrap).
- Artifacts are checked. The artifact validator rejects an
OP_REFwith an out-of-range selector or class operand.
7. Implementation map
| Concern | File |
|---|---|
Opcode OP_REF (182), selectors, packing macros, ABI minor 6 → 7 | impl/core/sleela_core.h |
Generation counter, destroy hook, ref_pack / ref_resolve_locked, the OP_REF case | impl/core/sleela_core.c |
| Artifact operand validation | impl/core/sleela_artifact.c |
x.ref, Ptr.*, Class.deref: type checking, read-only rule | impl/frontend/semantic.cpp |
Lowering and static typing of deref | impl/frontend/compiler.cpp |
| ISA registry and opcode map (the CI gates compare these with the enum) | lib/vm/InstructionSet.sleela, lib/vm/OPCODE-MAP.md |
| Normative language text | SLEELA.syntax §39, src/Sleela.formal-core §15.6 |
| Tests | impl/tests/refs/ (make test-ref) |
| Runnable reference | examples/pointers-demo.sleela |
OP_REF is one opcode. Its operand packs the selector in the low 4 bits and,
for deref, the class layout index above them: a = (typeIndex << 4) | selector.
8. Not yet
Honest boundaries of this first slice:
- No ref type in the type system. A ref is a plain
int, so the compiler cannot stop you passing the wrong int, andderefneeds the class named at the call (Target.deref(p)). A typed ref (aTarget&orPtr<Target>form) is the natural next step. - No pointers to fields, array elements, or arrays. Only class/struct instances have refs.
- No persistence. Refs are valid only within one run of one VM (§3.4).
- Introspection is numeric.
Ptr.typegives a layout index, not a class name, because strings are produced by a separate path. - No per-object accounting in the
[memory-manager]report; objects are invisible to it (§3.2). - No strong pin to keep an object alive through a ref.
- No virtual dispatch. Methods still bind statically by declared class
(§2), so
derefreturns the class you ask for, not the object's most-derived type. - The prebuilt
working-binaries/sleeladoes not include this yet. Build the compiler from source (cd impl && make -j8 build/sleela) to use it. Refreshing the committed binaries is a separate, documented procedure. - One naming pitfall, unrelated to refs: a variable named
nextis not an ordinary variable (nextis the language's degree word), sonext.refis rejected at runtime. Pick another name.
9. Tests
make test-ref (or bash impl/tests/refs/run_ref_tests.sh) checks:
- identity, the round trip through
deref, and two objects having different refs; - every tier-2 view;
- null, forged and out-of-range refs failing closed;
- wrong-class
derefreturningnull; - a declared field named
refwinning; - a ref going stale after a full collection, and a reused slot never aliasing;
x.ref = …, a non-int argument, and an unknownPtrfunction all rejected with the right message;- a user class named
Ptrtaking over the name; - the compiled artifact validating and running identically to the source.
Also kept green: the ISA verifiers (tools/verify-osls-isa-extension.py,
tools/verify-vm-source-coverage.sh, 183 opcodes) and the existing class-dispatch,
artifact-ABI, version, threads, Munction, OSLS, memory-manager and
unsigned-integer test targets. Two pre-existing failures are unrelated and
reproduce without this change: test-syntax-1.8 (a stale expected message for
constructor overloading) and the opt-in test-exceptions (its link recipe omits
-fopenmp).