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);

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() => Trequired

Makes 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>required

The 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).

returnsR

What 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>required

The region to enter.

argArequired

Outer memory f may read but not keep in the region (NL2610) or grow (NL2615).

f(root: T, arg: A) => Rrequired

Runs on the root and arg, answering as enter's does.

returnsR

What 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>required

The 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() => Trequired

Makes 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>