Runtime

1. Abstract

This RFC specifies the Aura runtime linked into application binaries: tracing GC, M:N task scheduler, async I/O reactor, exception personality support, panic/abort paths, timers, and C ABI FFI bridges. The runtime is shipped as libraries produced by the Rust toolchain and linked by aura build, not installed as a separate end-user package.

Toolchain today (2026-07-16): C runtime stub runtime/aura_rt.c linked by the C backend — println, exception frames (throw/catch object payloads), Array helpers, and GC MVP (aura_gc_alloc + free-all on exit). No M:N scheduler, channels, async I/O, or full concurrent GC yet.

2. Motivation

2.1 Problem statement

A GC + task language needs a coherent runtime ABI for codegen (RFC-004) and stdlib (RFC-007). Single-binary deploy requires the runtime to be linkable and stripable, with documented knobs for servers.

2.2 Why now

Without a runtime contract, compiler lowering and stdlib cannot stabilize.

2.3 Success metrics

3. Goals

• Provide GC, scheduler, I/O, exceptions as linked libraries.
• Stable runtime ABI for compiler-generated code (versioned).
• Observability hooks (metrics, tracing) without mandatory heavy agents.
• Minimal default footprint for CLIs; tunable for servers.

4. Non-goals

• Distributed runtime / cluster membership.
• JVM-compatible object model.
• Hot code reload / dynamic agent attach in v1.
• Guaranteed hard real-time latency.

5. Prior art & alternatives

6. Design

6.1 Overview

┌──────────────────────────────────────────┐
│              Application code            │
├──────────────────────────────────────────┤
│  Stdlib (Aura)                           │
├──────────────────────────────────────────┤
│  Runtime ABI (calls from codegen)        │
│  ┌────────┐ ┌──────────┐ ┌────────────┐  │
│  │  GC    │ │ Scheduler│ │  I/O poll  │  │
│  └────────┘ └──────────┘ └────────────┘  │
│  ┌────────┐ ┌──────────┐ ┌────────────┐  │
│  │Except. │ │  Timers  │ │ FFI / stubs│  │
│  └────────┘ └──────────┘ └────────────┘  │
├──────────────────────────────────────────┤
│  OS: threads, sockets, files, virtual mem│
└──────────────────────────────────────────┘

Runtime components may be implemented in Rust (and/or C for tiny stubs), exposed to LLVM codegen via known symbols (aura_rt_*).

6.2 GC

Safepoints: compiler inserts polls at back-edges and calls (policy with RFC-004).

6.3 Scheduler

• M:N tasks on a worker pool (default: CPU count).
• Work-stealing queues.
• Cooperative yield at await points; optional preemption via safepoint time slices (open).
• spawn, join, cancellation propagation for scopes.
• spawn_blocking for sync OS calls that would stall workers.

6.4 Async I/O

• Reactor integrates with OS primitives (epoll/kqueue/IOCP).
• Stdlib net/fs async APIs park tasks rather than blocking workers.
• Timers: min-heap / time wheel wheel in runtime.

6.5 Exceptions & panics

• Exceptions are language-level; runtime provides raise/unwind landing pads with LLVM EH.
• Uncaught exception in main → print diagnostic, exit non-zero.
• Uncaught in task → surface on join; if detached, log + default handler.
• Abort path for fatal OOM / corrupted runtime.

6.6 Allocation API (compiler ABI)

Illustrative symbols (names TBD):

aura_rt_alloc(size, type_id) -> ptr
aura_rt_alloc_array(elem_size, len, type_id) -> ptr
aura_rt_write_barrier(obj, field, new_value)  // if concurrent GC needs it
aura_rt_safepoint()
aura_rt_throw(exc_ptr) -> !
aura_rt_spawn(fn_ptr, env_ptr)
aura_rt_await(...)

Versioning: AURA_RT_ABI_VERSION checked at startup.

6.7 FFI

• C ABI extern declarations in Aura (extern "C" fun ...) lowered to LLVM.
• Libc linking as needed per target.
• Pin APIs for byte buffers across calls.
• Callbacks from C into Aura require runtime re-entry rules (documented).

6.8 Startup / shutdown

1. Runtime init (GC, scheduler, main thread).
2. Run static initializers (order rules: within package defined; across packages by dependency topo).
3. Call user main.
4. Drain tasks or cancel on exit policy.
5. Flush stdio; GC teardown optional.

6.9 Configuration

6.10 Examples

# build links libaura_rt
aura build -o app
./app
AURA_WORKERS=4 AURA_GC_MAX_HEAP=512m ./app

6.11 Error model / edge cases

6.12 Compatibility & migration

• Runtime ABI major bumps with toolchain major.
• Older binaries not guaranteed to load newer shared RT (static link default avoids this).

7. Open questions

8. Rationale & trade-offs

Linking the runtime into each binary matches single-file deploy and avoids “install runtime first.” Go-like scheduler matches language concurrency. Implementing RT in Rust aligns with the toolchain monorepo. Cost: larger binaries than freestanding C; mitigated by LTO/strip and feature flags (CLI vs server profiles).

9. Unresolved / future work

• Continuous profiling integration
• GC visualization tools
• Optional arena APIs for buffers
• Windows IOCP maturity checklist

10. Security & safety considerations

• Runtime is trusted computing base for all apps.
• FFI re-entry and callbacks are high-risk; document threat model.
• Allocator integrity checks in debug.
• Race detector memory overhead only when enabled.

11. Implementation plan (optional)

12. References

• Go runtime design talks/docs
• LLVM statepoints / EH docs
• RFC-003, RFC-004, RFC-007

Changelog