gizlang:functions

compiled units that a running program loads: new Function sources (JavaScript) and kernels (Gizlang functions over columns, which a database generates for a statement). The runtime finds the unit of a source by its sha256 in GIZLANG_CACHE/functions, or has $GIZLANG_CLI function HASH compile it, and loads it into this process. The unit's SDK calls bind to this program's SDK.

import * as Functions from "gizlang:functions";

Types

Columns

type Columns = { ints: Vec<Vec<i64>>; floats: Vec<Vec<f64>>; codes: Vec<Vec<u32>>; nulls: Vec<bytes>; params: Vec<i64>; rows: Vec<u32>; start: i64; end: i64; selected: Vec<u32>; words: Vec<i64>; reals: Vec<f64>; failed: bool; bits: Vec<Vec<u64>>; lanes: Vec<Vec<i32>>; shorts: Vec<Vec<i16>>; tinies: Vec<Vec<i8>>; }

What a kernel reads and writes. Each column is a whole stored column; the kernel reads rows rows of it, or every row in [start, end) when rows is empty. nulls has one byte a row (1: NULL) for each column, ints first, then floats, then codes, and is empty for a column with no NULL. params are values the caller computes for each run (a text constant's code in the column's dictionary). The kernel writes the rows it selects (selected) or its aggregates (words, reals), and sets failed when it cannot answer (an integer passed its width). A join's hash tables are more ints (a join kernel reads a build's dense array, key tables and rows), and its bit filters are bits. A scan's integer column whose values fit 32 bits is read as lanes (half the memory traffic), one that fits 16 bits as shorts (a quarter), one that fits 8 bits as tinies (an eighth), their nulls after the codes' in that order.

• ints: Vec<Vec<i64>>
• floats: Vec<Vec<f64>>
• codes: Vec<Vec<u32>>
• nulls: Vec<bytes>
• params: Vec<i64>
• rows: Vec<u32>
• start: i64
• end: i64
• selected: Vec<u32>
• words: Vec<i64>
• reals: Vec<f64>
• failed: bool
• bits: Vec<Vec<u64>>
• lanes: Vec<Vec<i32>>
• shorts: Vec<Vec<i16>>
• tinies: Vec<Vec<i8>>

Functions

load

function load(hash: string, source: string): Option<i64>

The address of the entry of the unit for SOURCE, the text function anonymous(P\n) {\nB\n} whose sha256 in lowercase hex is HASH. The entry has the type (heap: mut JS.Heap) => Result<JS.JsValue, string>: it runs the unit in heap, which sets the global property HASH to a function that returns a new closure of the source each call. None when no unit loads: no GIZLANG_CLI to compile one, or a source that does not compile. Each hash loads once in a process.

Effects: io.

loadError

function loadError(): string

Why the last load found no entry although a unit was there (its dlopen error), or "".

Effects: fail, io.

ready

function ready(hash: string, source: string): Option<i64>

The entry of the kernel unit for SOURCE (sha256 HASH, beginning with KERNEL_HEAD) when this process has it loaded, links it or finds it compiled in the cache; else none at once, and the first such call compiles it in the background for a later call. None always where no unit can load (no GIZLANG_CLI, wasm).

Effects: io.

run

function run(entry: i64, io: mut Columns): void

Runs the kernel ENTRY (ready) on io.

Effects: fail.

Constants

KERNEL_HEAD

const KERNEL_HEAD = "// gizlang:functions kernel\n"

The first line of a kernel's source: a Gizlang module whose export function gizlang_function(io: mut Columns): void reads the columns of io and writes its results there.