Home /Modules/vm/RUNTIME-SERVICES.md

RUNTIME-SERVICES.md

lib/vm/RUNTIME-SERVICES.md · 142 line(s) · markdown

SLeeLa Runtime Services Contract

Purpose

The SLVM generations share one language and one source-defined ISA, but the VM needs more than opcode dispatch. Networking, file I/O, sockets, process/thread execution, memory reclamation, and shutdown must have explicit lifecycle contracts.

This document is the common runtime-services construction for SLVM/1 through SLVM/11. It supplements the opcode map; it does not add hidden opcodes.

Services

ServiceContract
NetworkingAddress resolution, connection/listen/accept, nonblocking readiness, deadlines, cancellation, backpressure, bounded buffers, protocol errors, and capability checks.
File I/OOpaque VM handles, open/read/write/close/unlink, explicit ownership, EOF/error distinction, atomic close, platform adapters, and recovery-safe invalidation.
SocketsSockets are resources with states: NEW, BOUND, LISTENING, CONNECTING, CONNECTED, HALF_CLOSED, CLOSING, CLOSED, FAILED. Native descriptors/handles never escape the VM.
OS system callsHost System API access (environment, identity, working directory, filesystem metadata, and process execution) through the OP_OS_* opcodes / os* built-ins, serviced by impl/core/sleela_os.c on Windows (Win32), Linux, and macOS (POSIX). A spawned child process is a resource with states NEW, RUNNING, EXITED, FAILED, tracked as a VM-local bounded handle (never a raw PID/HANDLE); it is reaped by osWait/osProcessClose and force-released at VM teardown.
ThreadingStructured concurrency: every spawned execution has an owner/scope, cancellation token, join/detach policy, deadline, and terminal result. Unowned threads are rejected.
Garbage CollectionVM-managed heap objects use tracing reachability as the semantic baseline. Collection is incremental/generational where practical, with safepoints and write barriers. Native resources are not reclaimed by GC alone. Implemented in runtime/garbage_collector.c; verified and open points are in impl/RUNTIME-AUDIT.md.
TeardownShutdown is idempotent and ordered: stop admission, cancel child work, quiesce I/O, close sockets/files, join owned threads, drain deferred work, run finalizers for language objects, then release VM memory.
RecoveryStale handles and resources from an invalidated epoch fail closed and must be reacquired. Recovery never silently resurrects a native descriptor.

Modern execution model

1. Structured concurrency

SPAWN creates a child execution owned by the current VM scope. JOINALL is the legacy bulk-join primitive; the runtime service model additionally requires:

The existing pthread/Windows abstraction remains an OS adapter, not the language concurrency model.

2. Async-capable I/O

The language may retain synchronous source operations while the runtime service layer supports asynchronous implementations underneath them. Blocking operations must therefore be represented as cancellable resource waits rather than assuming that a native thread can always be abandoned.

The native backend may use poll/select/epoll/kqueue/IOCP or another platform appropriate mechanism. These are implementation choices; the SLeeLa semantic contract remains stable.

3. Resource ownership

Every file, socket, pipe, FIFO, network connection, thread, and pending I/O request has one explicit owner/scope and one terminal lifecycle. Close/cancel operations are idempotent. Double-close, use-after-close, stale-handle, and wrong-owner access return a runtime error rather than operating on a recycled native resource.

4. Garbage collection and native resources

GC manages language-visible heap objects. It does not make native OS resources implicitly safe to abandon.

A resource-owning object must have an explicit close/release path. Finalization is a backstop for language objects, not the primary mechanism for sockets, files, threads, or other scarce OS resources.

The collector should use:

5. Networking and sockets

Networking is capability-mediated. A connection must carry its address family, transport, peer/local identity, timeout/deadline, cancellation state, and lifecycle epoch.

Reads/writes distinguish:

A close transitions the resource toward CLOSED and wakes pending waiters. Half-close is represented explicitly where the transport supports it.

6. File I/O

File handles are opaque VM-local capabilities. Native descriptor numbers and Windows HANDLE values remain private to the platform adapter.

Open/read/write/close are subject to:

This builds on the existing impl/fileio platform boundary and SLVM/9 filesystem identity model.

7. Teardown state machine

RUNNING -> QUIESCING -> CANCELLING -> DRAINING -> JOINING -> CLOSING_RESOURCES -> FINALIZING -> STOPPED

Any unrecoverable lifecycle violation moves to QUARANTINED rather than reopening or silently reusing a resource.

The sequence is idempotent: repeated shutdown requests observe the current state and do not execute destruction twice.

Mapping to the 156-opcode ISA

The existing ISA already contains direct primitives for:

The OSLS call opcode dispatches 12 typed osls_* functions through a stable operation-ID table and returns bounded JSON Strings; C pointers and native record layouts never enter VM values. The OS process opcodes (OS_SPAWN/OS_WAIT/OS_KILL/OS_PCLOSE) reuse the same resource-ownership discipline as sockets and files: a spawned child is a VM-local bounded handle with an explicit terminal lifecycle, reaped on wait/close and released during teardown. GC, cancellation, ownership, deadlines, resource epochs, and teardown remain runtime services rather than one opcode per concept. This avoids bloating the ISA while allowing the native implementation and every VM generation to evolve.

Generation responsibilities

All generations preserve the same SLeeLa source semantics. A generation may add stronger validation or more capable adapters, but it must not weaken resource lifetime, cancellation, safety, or teardown guarantees.

Because the OP_OS_* system-call group is part of the one shared ISA, the host System Call API is available to every generation, SLVM/1 through SLVM/11 — not only the base VM. Each generation applies its existing resource-ownership and teardown rules to spawned processes exactly as it does to sockets and files (e.g. SLVM/8 enforces capability leases and audit over OS_RUN/OS_SPAWN; SLVM/9–11 bind process and filesystem-metadata calls to the storage-identity model). A generation may restrict or sandbox the OS surface via capability policy, but it inherits the same os* semantics the base VM exposes.

Standard GC implementation

The previous runtime GC placeholder has been replaced by the common collector in runtime/garbage_collector.c. It is a stable-handle, generational incremental tracer with explicit roots, safepoints, SATB-style pre-write protection, remembered old-to-young references, promotion, and deterministic full collection. The Core VM now owns one collector and treats struct instances as managed objects.

The C++ VM generations use lib/vm/include/sleela_vm_gc.hpp as an RAII facade over the same C collector. The source-side declarations are in lib/vm/GarbageCollector.sleela, GCObject.sleela, GCQuality.sleela, GCPermutation.sleela, GCRoot.sleela, and GCBarrier.sleela.

Collection is deliberately non-moving because the current SLeeLa value model uses stable VM-local handles. This avoids relocation complexity while preserving the modern collector invariants. Native sockets, files, threads and other OS resources remain governed by the resource-ownership/teardown layer rather than by GC reachability.