Regions

A region is memory your program frees when it says so. Ordinary objects in Nish live until the program ends, which is right for a program that runs and exits but not for a long-running one, such as a cache or a server that keeps state per connection. A region holds things that live and die together, and one free gives all of it back. The functions come from the built-in module nish:region. The rules are in the reference under Regions: nish:region.

Making, using and freeing a region

region(f) makes a region and runs f in it: every object f allocates lands in the region, and what f answers is the region's root. You get back a Region<T> handle, which is a number, not a pointer. enter(r, f) runs f(root) in the region again and answers what f answers. free(r) gives the memory back:

import { Region, enter, free, region } from "nish:region";

class Session {
  hits: i32 = 0;
}

const open = (): Session => new Session();

const touch = (s: Session): i32 => {
  s.hits = s.hits + 1;
  return s.hits;
};

export const main = (): i32 => {
  const r: Region<Session> = region(open);
  enter(r, touch);
  console.log(enter(r, touch));
  free(r);
  return 0;
};

That prints 2. f is an arrow or a named function, and an arrow inside a region captures nothing.

Passing a value in

regionWith(arg, f) and enterWith(r, arg, f) hand f one more argument: f(arg) and f(root, arg). Numbers that f copies out of the region, into an array it was given, are yours to keep after free:

import { Region, enterWith, free, regionWith } from "nish:region";

class Buffer {
  bytes: u8[];
  constructor(size: i32) {
    this.bytes = new Array<u8>(size);
    for (let k: i32 = 0; k < size; k++) {
      this.bytes[k] = 7;
    }
  }
}

const open = (size: i32): Buffer => new Buffer(size);

const copyOut = (b: Buffer, out: u8[]): i32 => {
  for (let k: i32 = 0; k < b.bytes.length && k < out.length; k++) {
    out[k] = b.bytes[k];
  }
  return b.bytes.length;
};

export const main = (): i32 => {
  const out = new Array<u8>(4);
  const r = regionWith(16, open);
  const n = enterWith(r, out, copyOut);
  free(r);
  console.log(n);
  console.log(out[3]);
  return 0;
};

That prints 16 and 7.

What may cross the edge

Once free runs, nothing outside the region may point into it, so the compiler checks every way a value can cross. A number, a boolean, an enum and a Region handle are copied, so they cross freely. An object, an array or a string made inside the region may not be kept by memory outside it:

import { enterWith, free, region } from "nish:region";

class Box {
  n: i32 = 0;
}

class Holder {
  box: Box | null = null;
}

const keep = (b: Box, h: Holder): i32 => {
  h.box = b;
  return 0;
};

export const main = (): i32 => {
  const h = new Holder();
  const r = region((): Box => new Box());
  const n = enterWith(r, h, keep);
  free(r);
  return n;
};

And enter may answer only something that is copied, never region memory:

import { enter, free, region } from "nish:region";

class Box {
  items: i32[];
  constructor() {
    this.items = [];
  }
}

const itemsOf = (b: Box): i32[] => b.items;

export const main = (): i32 => {
  const r = region((): Box => new Box());
  const xs = enter(r, itemsOf);
  free(r);
  return xs.length;
};

The other way is refused as well: memory from outside the region may not be stored into the region, and a region's function may not grow an array, Map or Set from outside it. A region's handle stays on the thread that made it, so it may not be handed to a task, a channel or a parallel body, and a region's function may not read Arena.mark or Arena.used. An arrow the function hands to a helper runs inside the region too, so its body is checked the same way. The reference lists each refusal with its code.

A region inside a region

Inside the f an enter runs, child(f) and childWith(arg, f) make a child region of the one entered. A child may point into its parent's memory that was there before this enter, so it can use the parent's strings and objects without copying them, and free of the parent frees every child too:

import { Region, childWith, enter, free, region } from "nish:region";

class Name {
  text: string;
  constructor(text: string) {
    this.text = text;
  }
}

class Use {
  name: Name;
  constructor(name: Name) {
    this.name = name;
  }
}

const open = (): Name => new Name("total");
const hold = (name: Name): Use => new Use(name);
const keep = (name: Name): Region<Use> => childWith(name, hold);
const length = (u: Use): i32 => u.name.text.length;

export const main = (): i32 => {
  const parent = region(open);
  const kid = enter(parent, keep);
  console.log(enter(kid, length));
  free(parent);
  return 0;
};

That prints 5, and after free(parent) the handle kid is dead as well. What the parent's f made during this enter may not go into the child: a scope inside the enter could give it back while the child still lives.

import { Region, childWith, enter, free, region } from "nish:region";

class Name {
  text: string;
  constructor(text: string) {
    this.text = text;
  }
}

class Use {
  name: Name;
  constructor(name: Name) {
    this.name = name;
  }
}

const open = (): Name => new Name("total");
const hold = (name: Name): Use => new Use(name);
const keep = (root: Name): Region<Use> => childWith(new Name(root.text), hold);

export const main = (): i32 => {
  const parent = region(open);
  enter(parent, keep);
  free(parent);
  return 0;
};

The child's memory may not be stored into the parent's, the child's f may not grow the parent's arrays, Maps or Sets, and child may be called only in the f an enter runs, never in a function something else also calls (NL2702). A plain region() made inside enter has no parent and keeps the rules above.

The child may keep the parent's root only while that root holds nothing the parent's f stored into it: once any code stores into memory the root may reach (a field, an array push, a Map.set, or a call that keeps its argument), the child may not keep it. Filling an array or Map the f made itself is fine, unless the root, or memory it reaches, was put into memory the f made. To keep a list of the parent's nodes, build it in the child's own f: it may push the parent's memory onto an array of the root it allocates, in its own body rather than in a helper it calls. Entering a handle that may be a child's gives an f whose root is the child's memory, so that root may neither take memory from outside nor be stored outside. A handle made by region() or regionWith() and never reassigned is not a child's and keeps the plain rules.

Mistakes stop the program

enter, enterWith and free check the handle each time. A handle that was never made, that is freed already or that belongs to another thread stops the program with a message, and so does entering a region that is already entered or freeing one that is (or a parent whose child is entered). Freeing twice is a stop, never a corruption. Under --deny-panics each of these calls is reported.

nish --emit-ts does not translate a program that imports nish:region yet (NL4015); build it native.