Home /Modules/impl/RUNTIME-SERVICES.md

RUNTIME-SERVICES.md

impl/RUNTIME-SERVICES.md · 41 line(s) · markdown

SLeeLa Runtime Services — Native Construction

This document maps the common runtime-services contract to the current native /impl substrate.

AreaCurrent constructionRequired model
NetworkingNative networking/platform smoke-test boundary and socket opcodes in the Core VMCapability-mediated, cancellable, deadline-aware, bounded I/O with explicit transport states
File I/O/impl/fileio, FILEOPEN/FILEREAD/FILEWRITE/FILECLOSE/FILEUNLINK, platform-specific handlesOpaque VM handles, ownership, short-I/O handling, EOF/error distinction, identity/epoch validation
SocketsLISTEN/ACCEPT/CONNECT/SOCKREAD/SOCKWRITE/SOCKCLOSEExplicit lifecycle, half-close, cancellation, deadlines, stale-handle rejection
ThreadingCore SPAWN/JOINALL/locks/mailboxes, pthread compatibility boundary, Windows threading adapterStructured concurrency with ownership, cancellation propagation, join results, safe points
Cancellationimpl/fundamental/CancellationToken.hpp exists as an atomic shared cancellation primitivePropagate tokens through VM scopes and blocking I/O; cancellation must be observable at safe points
Memory/impl/MEMORY_SYSTEM_OS.md provides allocation/page/time primitivesAdd VM heap ownership, precise roots, write barriers, safepoints, and incremental/generational GC
Garbage collectionImplemented in runtime/garbage_collector.c: tracing mark-sweep with incremental marking, a young/old split, a remembered set and write barriers (gc_write_barrier), VM root scanning (gc_mark_vm_roots) and a managed-heap limit (1 GiB, SLEELA_GC_LIMIT_BYTES). Allocation polls it at safepoints and, when a bounded table is full, runs one complete collection and retries (arrays, structs, Java Strings). GC is a runtime service, not an opcode.See impl/RUNTIME-AUDIT.md for what is verified and what is open (mark cost, native resources, thread-safety of the fast paths)
Teardownslvm_free and file cleanup exist; VM generations 7/8/10 have lifecycle/quiesce/recovery statesOrdered, idempotent quiesce/cancel/drain/join/close/finalize/stop state machine
RecoverySLVM/7–11 contain checkpoint/resource/filesystem identity conceptsStale native resources fail closed and are reacquired after epoch changes

Construction rule

The Core VM remains the semantic execution substrate. Runtime services sit below the ISA (195 opcodes, lib/vm/InstructionSet.sleela) and above the operating-system adapters. They may implement an opcode synchronously or asynchronously without changing its source meaning.

GC is intentionally not represented as a fake GC opcode. Allocation, safepoints, root scanning, barriers, and collection are runtime mechanisms. File descriptors, sockets, threads, pipes, and pending I/O are explicit resources and require deterministic close/cancel behavior even when the owning language object becomes unreachable.

See /lib/vm/RUNTIME-SERVICES.md for the generation-wide contract.

Required implementation order

  1. Establish a VM heap/object header and root-registration interface.
  2. Add safepoint polling to interpreter execution, allocation, calls/returns, loop back-edges, blocking I/O, and cancellation boundaries.
  3. Implement tracing collection with a simple stop-the-world baseline, then add incremental/generational collection behind the same interface.
  4. Add write barriers before enabling generational/incremental modes.
  5. Attach resource ownership/scope metadata to file, socket, pipe, and thread handles.
  6. Propagate cancellation and deadlines into blocking operations.
  7. Make teardown idempotent and observable, with double-close/use-after-close/stale-handle diagnostics.
  8. Add cross-platform stress tests for Linux, Windows, and macOS.

Standard GC implementation

The native runtime now uses the common generational incremental collector in runtime/garbage_collector.c. It provides stable-handle young/old generations, tri-colour incremental marking, explicit roots, safepoints, SATB-style pre-write protection, remembered old-to-young references, promotion and deterministic full collection. The Core VM owns one collector per VM and manages struct instances through it.

During active worker threads, reclamation is deferred until a structured-concurrency quiescent point so the current C VM does not scan unsafely moving thread stacks. Native resources remain under their explicit ownership/teardown APIs.