Runtime

Runtime behavior covers execution modes, memory boundaries, ownership,

concurrency, cleanup, and effect metadata.

Execution modes

Safety profile

--safe-mode gives Nytrix its compile-time safety profile. It promotes

ownership diagnostics to errors and adds RC/RAII cleanup, strict effect/alias

policy, and stricter raw-memory diagnostics.

Ordinary compilation runs the ownership/provenance pass in advisory mode by

default. It warns about tracked use-after-move, double release, releasing or

mutating an observed value, and escaping borrows, but it does not change the

heap policy or insert cleanup. This makes common lifetime mistakes visible

without turning small scripts into an annotation exercise.

ny --safe-mode file.ny
ny --mode=safe file.ny

In this profile, code scopes owned raw allocations with with ptr: name or

returns them through an ownership contract. Raw memory loads and stores against

a compiler-tracked allocation require a proven byte range:

with ptr: p = malloc(8){
   def int i = 3
   assert_compile_range(i, 0, 7, "byte index")
   store8(p, 65, i)
   assert(load8(p, i) == 65, "checked load")
}

If the compiler cannot prove the index range, or proves that index + width

exceeds the allocation size, compilation fails.

Managed and native boundaries

The runtime manages ordinary values. Raw pointers, handles, layouts, and FFI

strings cross into native memory and native lifetime rules.

Heap policy

The default heap path uses the native runtime allocator for runtime-managed

Nytrix objects. Standard library constructors such as strings, lists, dicts,

sets, tuples, and ordinary result values return managed Nytrix objects. Raw

buffers, external handles, FFI pointers, and memory returned by native APIs

still follow the owning API's explicit native ownership rules.

Enable the nursery/tenured GC with -gc or --heap=gc; the CLI sets the

runtime NYTRIX_GC switch from that policy.

ny -gc file.ny
NYTRIX_GC_NURSERY_SIZE=64M NYTRIX_GC_TENURED_SIZE=512M ny --heap=gc file.ny

With GC disabled, the collector reserves no nursery or tenured spaces. With GC

enabled, configure the nursery, tenured space, and large-object threshold with

NYTRIX_GC_NURSERY_SIZE, NYTRIX_GC_TENURED_SIZE, and

NYTRIX_GC_LOS_THRESHOLD. Size values accept bytes, K, M, or G.

GC mode changes allocation for managed Nytrix objects. Native handles and raw

buffers still need cleanup. Pair native allocations that escape the managed

object model with the owning API's cleanup function, with scopes, or a

release / forget contract.

Ownership

Declare ownership contracts with attributes. Compiler and runtime modes check

them. Resource APIs define whether a value is borrowed, owned, released, or

intentionally forgotten.

def b = borrow(a)
def c = &a
def o = own(value)
release(o)
forget(o)

&expr is the borrow operator and is equivalent to borrow(expr). own

marks a value as owned. release consumes and drops an owned value. forget

consumes an owned value without dropping it.

Ownership diagnostics run by default:

ny file.ny                         # advisory diagnostics, no cleanup changes
ny --ownership-strict file.ny      # diagnostics become errors
ny --ownership file.ny             # RAII cleanup plus diagnostics
ny --safe-mode file.ny             # strict safety profile

--borrow-check explicitly enables the default advisory pass. It reports

moves, releases, borrow escapes, use after move, and double release without

forcing RAII cleanup. --ownership-strict promotes these diagnostics to

errors and enables stricter tracking such as rejecting implicit borrows from

mutable slots. --ownership (alias for --heap=raii) enables automatic

runtime cleanup in addition to the analysis.

Use --no-borrow-check only for a legacy migration boundary. The compiler

still parses ownership attributes and keeps them as declaration metadata, but

does not issue advisory ownership diagnostics for that invocation.

Ownership function contracts are:

Scoped cleanup

defer and with provide cleanup. with uses the resource spelling

with Type: name = value { ... }.

defer { cleanup() }
with Resource: r = open_resource() { use(r) }

Concurrency

The runtime and standard library include stackless async tasks, OS threads,

atomics, queues, channels, and network async helpers. Shared state uses

synchronization APIs from std.core and std.os.

async starts a stackless task and await waits for its value:

use std.os.async (async, await)

fn plus_one(x){ x + 1 }

def h = async plus_one(41)
assert(await h == 42, "async result")

The callable form is also supported: async(fn_value, arg...) and

await(handle). await_all(handles) waits for a list of handles.

future(fn_value, arg...) and Future(fn_value, arg...) are compatibility

constructors for joinable async handles. sleep_ms(ms) and yield_now() are

async scheduling helpers in std.os.async.

Async socket helpers return awaitable handles for connect, accept, read, write,

and read-until operations.

Attributes and effects

Attributes describe declaration metadata: linkage, codegen hints, purity,

effects, hot/cold markers, accelerator/vectorization hints, and ownership

contracts.

@pure
@effects(none|io|alloc|ffi|thread|all)
@async_effects

@pure is shorthand for @effects(none).

Related

• control-flow.md for defer and with.
• native.md for FFI boundary rules.
• tooling.md for run modes and diagnostics.