# gizlang/profile

what a program says to its profile. Any Gizlang program profiles itself when GIZLANG_PROFILE names a file (`giz profile run -- PROGRAM`); `giz profile` then reads it. The runtime records tasks, I/O, children and samples by itself; this module adds what only the program knows: the phases of its run, the spans of its requests and steps, instants, counters and the owners of its memory. A span is the running task's until it ends, and the tasks it spawns meanwhile start in it, so the profile's causal graph ties their I/O and CPU to it. When the program is not profiled, each call costs one test.

```gizlang
import * as Profile from "gizlang/profile";
```

## Types

### `Span`

```gizlang
type Span = { id: i64; parent: i64; start: i64; name: string; }
```

A span of work: its id, the span it runs in, its start (`now`) and its name. Id 0 when nothing records.

- `id`: `i64`
- `parent`: `i64`
- `start`: `i64`
- `name`: `string`

## Functions

### `recording`

```gizlang
function recording(): bool
```

Whether this process records a profile now.

Effects: io, alloc.

### `kernels`

```gizlang
function kernels(): bool
```

Whether this process records each kernel of a GPU graph by itself (GIZLANG_PROFILE_GPU=kernels): the GPU work runs
unrecorded, kernel by kernel, slower but timed.

Effects: fail, io, alloc.

### `now`

```gizlang
function now(): i64
```

The profile's clock: CLOCK_MONOTONIC nanoseconds.

Effects: io, alloc.

### `newId`

```gizlang
function newId(): i64
```

A new id of a span or an operation, unique among this process's and naming it; 0 when nothing records.

Effects: io, alloc.

### `current`

```gizlang
function current(): i64
```

The running task's span, 0 for none.

Effects: io, alloc.

### `phase`

```gizlang
function phase(name: string): void
```

Starts the phase NAME of this program in its profile (a page's "load", then its "layout"): the part of the run that
follows, until the next phase. The report gives each its wall and CPU time, faults and memory.

Effects: fail, io, alloc.

### `label`

```gizlang
function label(at: u64, n: i64, name: string): void
```

Names the N bytes mapped at AT as NAME's in the owners of the profile's memory (a VM's heap, a model's weights).

Effects: fail, io, alloc.

### `begin`

```gizlang
function begin(name: string): Span
```

Starts the span NAME in the running one: the running task's span until it ends.

Effects: io, alloc.

### `join`

```gizlang
function join(name: string, parent: string): Span
```

Starts the span NAME as the child of PARENT, a span of another process (a traceparent's 16 hex digits): the
profile joins the two processes' graphs there.

Effects: fail, io, alloc.

### `mark`

```gizlang
function mark(name: string): void
```

The instant NAME.

Effects: fail, io, alloc.

### `guest`

```gizlang
function guest(vm: u64, links: i64, depth: i64, room: i64, exits: i64, callee: i64, info: i64, kind: i64, doubles: u64): u64
```

Makes the VM whose state is at VM (0: none) the guest stack of this thread's samples, read by its layout: the
state's words at LINKS, DEPTH, ROOM and EXITS, a frame's function at CALLEE from its frame pointer, a function's
info at INFO, its KIND, and values from DOUBLES up as numbers. Gives the VM it replaces.

Effects: fail, io, alloc.

### `guestName`

```gizlang
function guestName(info: u64, name: string): void
```

Names the guest function whose info is at INFO: samples show NAME where they hold it.

Effects: fail, io, alloc.

### `guestCode`

```gizlang
function guestCode(at: u64, size: i64, name: string): void
```

Names the SIZE bytes of compiled code at AT as the guest function NAME's: samples in that code show `jit NAME`.

Effects: fail, io, alloc.

### `counter`

```gizlang
function counter(name: string, value: i64): void
```

The value of the counter NAME now (queue depth, bytes held, tokens a second).

Effects: fail, io, alloc.

### `event`

```gizlang
function event(kind: i64, start: i64, end: i64, span: i64, parent: i64, resource: i64, bytes: i64, status: i64, a: i64, b: i64, text: string): void
```

An event of KIND with every field (gizhw/gpu's kernels and copies, on the GPU's clock mapped to this one).

Effects: fail, io, alloc.

### `traceSpan`

```gizlang
function traceSpan(): string
```

The 16 lowercase hex digits of the running span, as a traceparent's parent id; "" when nothing records or no span
runs (a traceparent's span is never all zeros).

Effects: fail, io, alloc.

### `traceId`

```gizlang
function traceId(): string
```

The 32 hex digits of this process's trace id, for a traceparent this process starts.

Effects: fail, io, alloc.

## Methods

### `Span.end`

```gizlang
function Span.end(self: Span): void
```

Ends the span: its parent runs again.

Effects: fail, io, alloc.

### `Span.finish`

```gizlang
function Span.finish(self: Span, bytes: i64, status: i64, resource: i64): void
```

Ends the span with what it did: the BYTES it moved, its STATUS (0 ok) and the RESOURCE it used (a descriptor, a
table, a model slot).

Effects: fail, io, alloc.

## Constants

### `SPAN`

```gizlang
const SPAN: i64 = Wire.PROFILE_SPAN
```

The kind of a span event: a named piece of work with a start and an end. The runtime numbers every kind.

### `MARK`

```gizlang
const MARK: i64 = Wire.PROFILE_MARK
```

The kind of a mark: an instant with a name.

### `COUNTER`

```gizlang
const COUNTER: i64 = Wire.PROFILE_COUNTER
```

The kind of a counter: a named value at an instant.

### `LINK`

```gizlang
const LINK: i64 = Wire.PROFILE_LINK
```

The kind of a link: one span waits for or follows another.

### `GPU_KERNEL`

```gizlang
const GPU_KERNEL: i64 = Wire.PROFILE_GPU_KERNEL
```

The kind of a GPU kernel: its run on the device, on the CPU clock.

### `GUEST`

```gizlang
const GUEST: i64 = Wire.PROFILE_GUEST
```

The kind of a VM's function (gizvm): the info that samples name it by, and its name, file and line.

### `GUEST_CODE`

```gizlang
const GUEST_CODE: i64 = Wire.PROFILE_GUEST_CODE
```

The kind of a VM's compiled code (gizvm): its address, size and the name of its function.

### `GPU_COPY`

```gizlang
const GPU_COPY: i64 = Wire.PROFILE_GPU_COPY
```

The kind of a GPU copy: bytes between host and device, or on the device.

### `GPU_GRAPH`

```gizlang
const GPU_GRAPH: i64 = Wire.PROFILE_GPU_GRAPH
```

The kind of a GPU graph replay.

### `GPU_MEMORY`

```gizlang
const GPU_MEMORY: i64 = Wire.PROFILE_GPU_MEMORY
```

The kind of a GPU allocation or release.

### `GPU_SYNC`

```gizlang
const GPU_SYNC: i64 = Wire.PROFILE_GPU_SYNC
```

The kind of a wait for the GPU.

### `DEVICE_GIVEN`

```gizlang
const DEVICE_GIVEN: i64 = Wire.PROFILE_DEVICE_GIVEN
```

A device buffer given, whose stack the runtime adds, and dropped (gizhw/gpu): resource is its address.

### `DEVICE_FREED`

```gizlang
const DEVICE_FREED: i64 = Wire.PROFILE_DEVICE_FREED
```

A device buffer given before (DEVICE_GIVEN) and now freed: resource is its address.

### `GPU_LAUNCH`

```gizlang
const GPU_LAUNCH: i64 = Wire.PROFILE_GPU_LAUNCH
```

A kernel or replay launched, whose stack the runtime adds: span is the id its GPU_KERNEL or GPU_GRAPH event takes.

### `GPU_WORK`

```gizlang
const GPU_WORK: i64 = Wire.PROFILE_GPU_WORK
```

A kernel's work (Gpu.work), beside its GPU_KERNEL event: a = its operations, b = the bytes it moves, text its name.

