nish:region
Memory a program frees when it says so: an arena of its own, reached through a handle, so that what lives and dies together goes back with one free where the thread's arena would hold it until the program ends.
The nish:region builtin module, whose source is std/region.ts. A program imports it as nish:region; the compiler refuses nish/region. The language reference is the normative list.
import {
Region,
child,
childWith,
enter,
enterWith,
free,
region,
regionWith,
} from "nish:region";
import { Region, enter, enterWith, free, region, regionWith } from "nish:region";
class Session {
hits: i32 = 0;
payload: u8[];
constructor(size: i32) {
this.payload = new Array<u8>(size);
}
}
const open = (size: i32): Session => new Session(size);
const serve = (s: Session, out: u8[]): i32 => {
s.hits = s.hits + 1;
for (let k: i32 = 0; k < s.payload.length && k < out.length; k++) {
out[k] = s.payload[k]; // a number is copied out
}
return s.payload.length;
};
const r: Region<Session> = regionWith(16, open);
const n: i32 = enterWith(r, new Array<u8>(64), serve);
free(r);
child
A new region whose parent is the region entered now: f() runs with every allocation landing in it, and what it answers is the root.
childWith
child, with one outside argument handed to f.
enter
f(root), with every allocation landing in the region.
enterWith
f(root, arg), under enter's rules.
free
Give the region's memory back: r and every copy of it are dead.
region
A new region: f() runs with every allocation landing in it, and what it answers is the root.
regionWith
region, with one outside argument handed to f.
Region
A handle to a region whose root is a T: 64 bits, not a pointer.
Each function's f is an arrow or a named function, and an arrow captures
nothing (NL2335), so the ways into a region are its root, arg and module
state. The checker tells region memory (the root, and whatever f
allocates) from outer memory (arg, module state, what a callee answers
from outside). A number, a boolean, an enum and a Region are copied,
never pointed at, so they cross freely.
Region memory stored into outer memory is NL2609, and outer memory other
than a number, boolean, enum or string literal stored into region
memory NL2610. Outer storage may not grow inside f (NL2615), threads may
not start there (NL2612), a value holding a Region may not cross to
another thread (NL2613), and Arena.mark and Arena.used are refused there
(NL2617). None of the five (region, regionWith, enter, enterWith,
free) runs in a parallel body or a spawned function (NL2351), and using
does not take a region (NL2387).
Every call checks its handle at run time
enter, enterWith and
free stop the program on a handle that is 0, freed already or another
thread's, and enter of an entered region and free of one stop it too,
so freeing twice is a panic and never a double free. Past 16,777,216 live
regions region stops the program as well.
Under Node
runtime/nish.mjs keeps a region as an entry in a table,
free drops it, and the same handle checks throw. --emit-ts refuses the
module (NL4015).
Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#regions-nishregion
Functions
child
A new region whose parent is the region entered now: f() runs with every
allocation landing in it, and what it answers is the root. The child may
keep memory the parent's root reaches, and free of the parent frees it
too. Called outside an enter or enterWith f it is NL2702, and it
stops the program when no region is entered.
const child: <T>(f: () => T) => Region<T>
f() => TrequiredMakes the root. It answers memory it allocated, never the parent's (NL2614).
returnsRegion<T>The handle.
childWith
child, with one outside argument handed to f.
const childWith: <A, T>(
arg: A,
f: (arg: A) => T,
) => Region<T>
argArequired
Memory the parent's root reaches, which f may keep in the
child, or outer memory it may only read (NL2610).
f(arg: A) => Trequired
Makes the root from arg. It answers memory it allocated, never
arg itself (NL2614).
returnsRegion<T>The handle.
enter
f(root), with every allocation landing in the region. Stops the program
on a dead, foreign or already-entered handle.
const enter: <T, R>(r: Region<T>, f: (root: T) => R) => R
rRegion<T>requiredThe region to enter.
f(root: T) => Rrequired
Runs on the root. It answers a number, a boolean, an enum or
a Region, never an array, an object or a string (NL2611).
returnsRWhat f answers.
enterWith
f(root, arg), under enter's rules.
const enterWith: <T, A, R>(
r: Region<T>,
arg: A,
f: (root: T, arg: A) => R,
) => R
rRegion<T>requiredThe region to enter.
argArequired
Outer memory f may read but not keep in the region (NL2610)
or grow (NL2615).
f(root: T, arg: A) => RrequiredRuns on the root and arg, answering as enter's does.
returnsRWhat f answers.
free
Give the region's memory back: r and every copy of it are dead. Stops
the program on a dead, foreign or entered handle, so freeing twice is a
panic.
const free: <T>(r: Region<T>) => void
rRegion<T>requiredThe region to free.
region
A new region: f() runs with every allocation landing in it, and what it
answers is the root.
const region: <T>(f: () => T) => Region<T>
f() => TrequiredMakes the root. It answers memory it allocated, never a module value (NL2614).
returnsRegion<T>The handle.
regionWith
region, with one outside argument handed to f.
const regionWith: <A, T>(
arg: A,
f: (arg: A) => T,
) => Region<T>
argArequired
Outer memory f may read but not keep in the region (NL2610)
or grow (NL2615).
f(arg: A) => Trequired
Makes the root from arg. It answers memory it allocated, never
arg itself (NL2614).
returnsRegion<T>The handle.
Classes
Region
A handle to a region whose root is a T: 64 bits, not a pointer.
class Region<T>

