Home /Modules/docs/POINTERS.md

POINTERS.md

docs/reference/POINTERS.md · 367 line(s) · markdown

<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.ref is 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 SLeeLaNotes
&obj — address ofobj.refan int; 0 is the null ref
*p — follow itClass.deref(p)the object, or null — never a crash
p == q — same objectp == qrefs are ints; equal refs name one incarnation
p == nullptrp == 0null.ref is 0
weak_ptr::expired()!Ptr.valid(p)
weak_ptr::lock()Class.deref(p)null when expired
dangling pointer (UB)stale refdetected, reads as invalid
sizeof(*p), typeidPtr.bytes(p), Ptr.type(p)tier-2 views
pointer arithmetic over memorynot supportedsee §5
reinterpret_cast, raw bytesnot possibleby 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.

AspectWhat tier 1 contains
TypeA class name. Nominal and static: Target. Single inheritance (syntax ≥ 1.10), base fields placed first.
StateThe 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).
BehaviourThe 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.
Constructionnew 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).
Accessobj.field, obj.method(...); protected methods are checked; static methods are called through the class.
LifetimeReachability only. There is no destructor and no reference count; the collector reclaims what is unreachable.
Visible limits64 fields per class, 4,096 live objects per VM, 65,536 distinct class/struct layouts.
CastsOP_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):

QuantityValue
sizeof(SLValue)32 bytes (16-byte aligned, because of its 128-bit integer member)
sizeof(SLStructInstance) — one object2,080 bytes
&nbsp;&nbsp;header (active, type)16 bytes
&nbsp;&nbsp;fields[64]64 × 32 = 2,048 bytes, at offset 16
&nbsp;&nbsp;gc_object pointeroffset 2,064
&nbsp;&nbsp;generation (31-bit incarnation counter)offset 2,072 — fits existing padding, no size cost
sizeof(SLGCObject) — the collector's record56 bytes
Instance storeSL_MAX_STRUCTS (4,096) × 2,080 = 8,519,680 bytes, allocated lazily

3.1 The VM lens

How the virtual machine represents the object.

ItemDetail
ValueA tagged value { type = SL_STRUCT, h = <int32 slot> }. The slot is an index into the VM's instance store, not an address.
Instance recordSLStructInstance { active, type, fields[64] of SLValue, gc_object, generation }. Field storage is dense; a field's offset is its declaration index.
LayoutOne 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.
OpcodesOP_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 validityA slot is valid when it is in range and active.
ConcurrencyThe store is guarded by struct_mtx.
Read withPtr.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.

SystemDoes an object belong to it?Detail
The garbage collector (runtime/garbage_collector.*)YesA 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)NoA 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.
ItemDetail
SizePtr.bytes(p) — the payload registered with the collector (2,080 for any class instance).
Age / generationPtr.age(p) counts collections survived; Ptr.old(p) is true once promoted to the old generation.
VM-widePtr.live() = active instances; Ptr.limit() = the 4,096 ceiling.
LifecycleAllocated 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.

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.

BoundaryHow it is kept
Tier 1 ↔ tier 2Tier 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 ↔ memoryA 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 ↔ objectClass.deref also checks the target is an instance of Class; a ref that lands on a different class reads as null.
VM ↔ VM / run ↔ runA 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 ↔ threadThe store is shared and mutex-guarded; collection is deferred while workers run.
ISATier 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

Operation on a bad refResult
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)

5. Language surface

FormTypeMeaning
x.refintthe ref of object x; 0 when x is null
Class.deref(p)Classthe object, or null if p is invalid or not a Class
Ptr.valid(p)booleanslot occupied by the same incarnation
Ptr.old(p)booleanpromoted to the old generation
Ptr.id(p)intslot index (-1 if invalid)
Ptr.gen(p)intslot incarnation
Ptr.type(p)intlayout (class) index
Ptr.fields(p)intnumber of field slots in use
Ptr.bytes(p)intinstance size as the collector counts it
Ptr.age(p)intcollections survived
Ptr.live()intactive objects in the VM
Ptr.limit()intobject-store ceiling (4,096)

Rules:

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

  1. 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.
  2. Every use is validated (range, active, generation, and — for deref — class).
  3. No use-after-free by aliasing. A reclaimed slot's generation moves on, so old refs cannot name the object that reuses it.
  4. No resurrection hazard. deref shades the object during incremental marking.
  5. Closed under bad input. NaN, negatives, huge values and null all fail closed (§4.2).
  6. 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).
  7. Artifacts are checked. The artifact validator rejects an OP_REF with an out-of-range selector or class operand.

7. Implementation map

ConcernFile
Opcode OP_REF (182), selectors, packing macros, ABI minor 6 → 7impl/core/sleela_core.h
Generation counter, destroy hook, ref_pack / ref_resolve_locked, the OP_REF caseimpl/core/sleela_core.c
Artifact operand validationimpl/core/sleela_artifact.c
x.ref, Ptr.*, Class.deref: type checking, read-only ruleimpl/frontend/semantic.cpp
Lowering and static typing of derefimpl/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 textSLEELA.syntax §39, src/Sleela.formal-core §15.6
Testsimpl/tests/refs/ (make test-ref)
Runnable referenceexamples/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:


9. Tests

make test-ref (or bash impl/tests/refs/run_ref_tests.sh) checks:

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).