# Runtime Dispatch

> StringZilla for JavaScript

Every call runs on the CPU and dispatches to the best kernel of its enabled capabilities, a `BigInt` bitmask a `Device` reports:

```javascript
const cpu = sz.Device.cpu();
console.log(cpu.capabilitiesEnabled()); // what dispatch uses
console.log((cpu.capabilitiesEnabled() & sz.Capability.haswell) !== 0n);
```

`capabilitiesEnabled()` is the one you usually want, and derives from two independent axes:

- `capabilitiesDetected()`: what this device can execute.
- `capabilitiesCompiled()`: what this build contains for devices of its kind, from the ISA probes at build time.
- `capabilitiesEnabled()`: what dispatch uses, both axes at once.

`capabilitiesDetected()` describes the machine and says nothing about whether a kernel was compiled in, so a build whose ISA probes failed still reports your CPU's full feature set while containing no SIMD kernels at all.
The enabled set always keeps the `serial` fallback.

A `Device` is the host CPU or one GPU of a runtime, named by that runtime's own ordinal:

```javascript
sz.Device.count("cpu");            // 1
const gpu = new sz.Device("cuda"); // throws without a CUDA device, or past the last one
gpu.capabilitiesEnabled();         // what that GPU runs, like `Capability.cuda`
```

- `Device.cpu()` is the host CPU, which every build has.
- `Device.count(kind)` counts the devices of `"cpu"`, `"cuda"`, `"rocm"` or `"metal"`, and throws without a GPU of that kind.
- `new Device(kind, ordinal)` throws a `RangeError` past the last device.

`Capability` maps each lowercase capability name, like `haswell`, `neon` or `cuda`, to its bit, and the `cpus`, `devices` and `any` groups to theirs.
It is built at load from the C library's own names.

There is no `configure_thread` call in the JS binding.
Thread configuration is managed internally by the native addon.

`import * as stringzilla from 'stringzilla';`

`import { Device } from 'stringzilla';`

`import { DeviceConstructor } from 'stringzilla';`

## CapabilityName

A capability name, as [`Capability`](https://www.unum.cloud/docs/stringzilla/javascript/types.md#Capability) keys it: one capability, or the `cpus`, `gpus` and `any` groups.

```typescript
type CapabilityName = | "serial" | "westmere" | "goldmont" | "haswell" | "skylake" | "icelake" | "neon" | "neonaes" | "neonsha" | "sve" | "sve2" | "sve2aes" | "rvv" | "rvvcrypto" | "v128" | "v128relaxed" | "loongsonasx" | "powervsx" | "cuda" | "hopper" | "blackwell" | "rocm" | "metal" | "cpus" | "gpus" | "any"
```

## DeviceKind

The runtime a device belongs to.

```typescript
type DeviceKind = "cpu" | "cuda" | "rocm" | "metal"
```

## Device

One device StringZilla knows: the host CPU, or a GPU by its runtime's own ordinal, the one `cudaSetDevice` or `hipSetDevice` takes, or the position in Metal's device list.

```typescript
interface Device
```

Every call of this binding runs on the CPU and dispatches over its
[`Device.capabilitiesEnabled`](#capabilitiesEnabled), so a GPU device only reports its masks here.

## capabilitiesDetected

The capabilities this device runs, compiled in or not, as a bitmask.

```typescript
capabilitiesDetected(): bigint
```

## capabilitiesCompiled

The capabilities compiled into this build for devices of this kind, as a bitmask.

```typescript
capabilitiesCompiled(): bigint
```

## capabilitiesEnabled

The capabilities this device's calls run: detected and compiled at once, as a bitmask.

```typescript
capabilitiesEnabled(): bigint
```

On the CPU it always includes [`Capability.serial`](https://www.unum.cloud/docs/stringzilla/javascript/types.md#Capability).

## kind

The runtime the device belongs to.

```typescript
readonly kind: DeviceKind
```

## ordinal

The runtime's own index of the device.

```typescript
readonly ordinal: number
```

## DeviceConstructor

Constructs a [`Device`](#Device) and counts the devices of a kind.

```typescript
interface DeviceConstructor
```

## DeviceConstructor

```typescript
new DeviceConstructor(kind: DeviceKind, ordinal?: number): Device
```

- `kind`: The runtime the device belongs to
- `ordinal`: The runtime's own index of the device, below
[`DeviceConstructor.count`](#count)

Throws: Without a device of [`kind`](#kind), or past the last one

## cpu

The host CPU, which every build has.

```typescript
cpu(): Device
```

## count

How many devices of [`kind`](#kind) the process sees: one CPU, or the GPUs its runtime counts.

```typescript
count(kind: DeviceKind): number
```

Throws: Without a GPU of [`kind`](#kind)