# 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.

```gizlang
import * as Functions from "gizlang:functions";
```

## Types

### `Columns`

```gizlang
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`

```gizlang
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`

```gizlang
function loadError(): string
```

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

Effects: fail, io.

### `ready`

```gizlang
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`

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

Runs the kernel ENTRY (ready) on `io`.

Effects: fail.

## Constants

### `KERNEL_HEAD`

```gizlang
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.