Executors | UForm for JavaScript

A model on GPUs takes a VRAM executor and lands its outputs in device memory, which no host view reads:

const gpus = Executor.forVram({ devices: [0, 1] });
const resident = Model.loadVram("model.safetensors", { executor: gpus, devices: [0, 1] });

Device ordinals are positions in gpuDevices(), NVIDIA devices first, then AMD.

API

Types

MeshOptionsWhere this process sits among the processes training one model, and how they meet.

uform.ts:34 ↗

interface MeshOptions

Mirrors uform_mesh_options_t.

Fields

`hostDomainIndex?`	`number`	This process's index among `hostDomainCount`.
`hostDomainCount?`	`number`	Processes in the run, one per host; absent derives one, a run with no peers.
`gpusPerMultimemDomain?`	`number`	GPUs one NVLink multicast domain spans; absent derives the host.
`directory?`	`string`	The path of the directory every host sees, crossing as its UTF-8 bytes; required with peers.
`job?`	`string`	The run's unique name, naming one directory inside `directory`; required with peers.
`timeoutSeconds?`	`number`	Seconds any wait for a peer lasts before the call fails; absent derives 120.

MeshDescriptionWhat a mesh reports about itself.

uform.ts:51 ↗

interface MeshDescription extends Omit<CompiledMeshDescription, "multimemTier">

Mirrors uform_mesh_description_t.

Fields

`multimemTier`	`MultimemTier`	How its NVLink domains reduce.

MultimemTierHow a mesh's NVLink domains reduce.

uform.ts:124 ↗

enum MultimemTier

Values

`SwitchReduced`	`"switch-reduced"`
`PeerRead`	`"peer-read"`

GpuVendorThe runtime that drives a GPU, numbered as uform_gpu_vendor_t numbers them.

uform.ts:169 ↗

enum GpuVendor

Values

`Unknown`	`0`
`Nvidia`	`1`
`Amd`	`2`
`Apple`	`3`

GpuDeviceOne GPU this process can drive.

uform.ts:177 ↗

interface GpuDevice

Mirrors uform_gpu_device_t.

Fields

`vendor`	`GpuVendor`	The vendor whose runtime drives the device.
`vendorOrdinal`	`number`	The device's ordinal in its vendor's runtime, as `nvidia-smi` or `rocm-smi` lists it.
`gpuClass`	`string \| null`	The class whose kernels run on it, as `uform_gpu_class_name` spells it, like "nvidia-hopper".
`computeUnits`	`number`	Streaming multiprocessors or compute units.
`memoryBytes`	`number`	Device memory in bytes.
`name`	`string`	The vendor's own name for the device.

ExecutorForRamConfigWhere the host threads of a RAM executor are placed, how many there are, and how many deferred calls it tracks.

uform.ts:250 ↗

interface ExecutorForRamConfig

Fields

`memoryDomains?`	`number[]`	NUMA node IDs the threads are spread over; absent spreads them over every node.
`cpuClass?`	`string`	The CPU class to dispatch as, spelled like "intel-haswell"; absent derives the CPU's own.
`threads?`	`number`	Threads to spawn; absent takes 7/8 of the cores the domains carry.
`deferredLimit?`	`number`	Deferred calls tracked at once; absent takes a default.

ExecutorOnPoolConfigWhere the borrowed pool of a RAM executor is placed, and how many deferred calls it tracks.

uform.ts:262 ↗

interface ExecutorOnPoolConfig

Fields

`memoryDomains?`	`number[]`	NUMA node IDs of the models it will drive; absent derives every node.
`cpuClass?`	`string`	The CPU class to dispatch as, spelled like "intel-haswell"; absent derives the CPU's own.
`deferredLimit?`	`number`	Deferred calls tracked at once; absent takes a default.

ExecutorForVramConfigWhich devices a VRAM executor drives, and on which streams.

uform.ts:272 ↗

interface ExecutorForVramConfig

Fields

`devices?`	`number[]`	Device ordinals, positions in `gpuDevices`, to drive; absent takes one free device.
`gpuClass?`	`string`	The GPU class every device dispatches as, spelled like "nvidia-hopper"; absent derives the devices' own.
`memoryDomains?`	`number[]`	NUMA node IDs whose cores the host decoders take; absent takes every node.
`cpuClass?`	`string`	The CPU class the host decoders dispatch as, spelled like "intel-haswell"; absent derives the CPU's own.
`streams?`	`bigint[]`	Borrowed CUDA stream addresses, one per device in `devices` order; absent creates its own.
`scratchLimit?`	`number`	Ceiling on scratch bytes per device; absent lets scratch grow as batches ask.
`deferredLimit?`	`number`	Deferred calls tracked at once; absent takes a default.

ClassMeshOne process's place among the processes of a run, made once and borrowed by every trainer.4

train.ts:60 ↗

class Mesh implements Disposable

bootstrapJoins this process to the run's mesh, once every process has joined.

train.ts:76 ↗

static bootstrap(
    executor: Executor,
    options: MeshOptions = {},
): Mesh

Calls uform_mesh_bootstrap.

Parameters

`executorExecutor`		A VRAM executor whose devices are this process's members of the mesh.
`optionsMeshOptions`		Where this process sits and how the processes meet.

describeReports the mesh's shape and this process's place in it.

train.ts:81 ↗

describe(): MeshDescription

Calls uform_mesh_describe.

freeLeaves the mesh; every trainer borrowing it must be freed first.

train.ts:87 ↗

free(): void

Calls uform_mesh_free.

compiledThe backend handle a trainer borrows.

train.ts:62 ↗

readonly compiled: CompiledMesh

ClassExecutorThe threads or streams a verb runs on, shared across models.6

types.ts:303 ↗

class Executor implements Disposable

An executor owns host threads or device streams and the activation scratch; a model owns weights. Keeping them apart is what lets one executor serve several models, and what makes the cost of spawning visible at the line that spawns it. The WebAssembly backend computes on the calling thread alone, so its executors only order calls. The collector frees it eventually; free joins the threads now.

forRamSpawns host threads for RAM-resident models.

types.ts:315 ↗

static forRam(config: ExecutorForRamConfig = {}): Executor

Calls uform_executor_for_ram.

forVramOpens one stream per device for VRAM-resident models.

types.ts:320 ↗

static forVram(config: ExecutorForVramConfig = {}): Executor

Calls uform_executor_for_vram.

onPoolBorrows a ForkUnion fu_pool_t by address, which reports unsupported until borrowing is designed.

types.ts:326 ↗

static onPool(
    pool: bigint,
    config: ExecutorOnPoolConfig = {},
): Executor

Calls uform_executor_on_pool.

drainWaits for every call submitted to this executor so far, then idles in mood.

types.ts:335 ↗

drain(mood: Mood = Mood.Parked): void

Calls uform_executor_drain.

Parameters

`moodMood`		What the threads or streams do once they go idle.

freeRuns every deferred call and joins the threads now; a second free does nothing.

types.ts:341 ↗

free(): void

Calls uform_executor_free.

compiledThe backend handle every verb is handed.

types.ts:305 ↗

readonly compiled: CompiledExecutor

Functions

gpuDevicesLists every GPU this process can drive, NVIDIA devices first, then AMD, so a device's position is the ordinal VRAM placements name it by; a machine without GPUs lists none.

uform.ts:244 ↗

function gpuDevices(): GpuDevice[]

Calls uform_gpu_devices.

capabilitiesCompiledThe hardware capabilities this binary was compiled with, comma-separated.

uform.ts:70 ↗

function capabilitiesCompiled(): string

Calls uform_capabilities_compiled.

capabilitiesAvailableThe hardware capabilities the current machine offers at runtime, comma-separated.

uform.ts:76 ↗

function capabilitiesAvailable(): string

Calls uform_capabilities_available.