# Design

> UForm for Mojo

Blocking stays simple: a verb on the model or on `model.on(executor)` reads as it would if asynchrony did not exist.
Deferred calls are symmetric, the same verbs on another receiver, observed only through the outcome's status word, and release rides Mojo's own destructor.
Nothing costs anything until used: the binding starts no threads, keeps no counts and caches nothing, so a call is one argument structure built on the stack and one indirect call.

`from uform import Library`

## Library

A reference to the loaded engine, cheap to copy and shared by everything it creates.

```mojo
struct Library
```

Every handle carries one, which is what keeps the shared object mapped for as long as anything
can still call into it. It is a loader reference and nothing more: an executor never retains a
model, and a model never retains an executor.

- `shared` `ArcPointer[_Loaded]`: The handle and its symbols, refcounted so the last holder unmaps the object.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Opens the shared object and resolves it, which every handle then shares.

```mojo
def __init__(out self)
```

Raises: With [`LIBRARY_MISSING`](https://www.unum.cloud/docs/uform/mojo/errors.md#LIBRARY_MISSING), when nothing is on the loader path, with [`VERSION_MISMATCH`](https://www.unum.cloud/docs/uform/mojo/errors.md#VERSION_MISMATCH) when what loaded is another major version, or with [`SYMBOL_MISSING`](https://www.unum.cloud/docs/uform/mojo/errors.md#SYMBOL_MISSING) when it does not export an entry point the binding needs.

## symbols

The resolved entry points, borrowed rather than copied on every call.

```mojo
def symbols(self) -> ref[self.shared.symbols] Symbols
```

## version

The loaded engine's major, minor and patch, which may differ from what this binding was written against within one major. Calls `uform_version`.

```mojo
def version(self) -> Tuple[Int, Int, Int]
```

## version_name

The loaded engine's own version, which is also the cheapest check that loading worked. Calls `uform_version_name`.

```mojo
def version_name(self) -> String
```

## capabilities_compiled

The hardware capabilities this build of the engine was compiled with, comma-separated. Calls `uform_capabilities_compiled`.

```mojo
def capabilities_compiled(self) -> String
```

## capabilities_available

The hardware capabilities this machine offers now, which the build does not imply. Calls `uform_capabilities_available`.

```mojo
def capabilities_available(self) -> String
```

## gpu_devices

Fills `devices` with every GPU this process can drive, in the ordinal order every VRAM call names them by. Calls `uform_gpu_devices`.

```mojo
def gpu_devices[devices_origin: MutOrigin, //](
    self,
    devices: Span[GPUDevice, devices_origin]
) -> Int
```

- `devices`: Where the listing lands, as many entries as fit; may be empty to only count.

Raises: [`Error`](https://www.unum.cloud/docs/uform/mojo/errors.md#Error) if a vendor runtime is present but refuses the listing.

## status_name

The engine's spelling of a status, "unrecognized" for a code it does not name. Calls `uform_status_name`.

```mojo
def status_name(self, status: Status) -> String
```

## status_from_name

Reads a spelling back; [`INVALID_ARGUMENT`](https://www.unum.cloud/docs/uform/mojo/errors.md#INVALID_ARGUMENT) when unrecognized. Calls `uform_status_from_name`.

```mojo
def status_from_name(self, name: StringSpan) -> Status
```

## scalar_name

The engine's spelling of a scalar kind, as [`F32`](https://www.unum.cloud/docs/uform/mojo/encoding.md#F32) spells "f32". Calls `uform_scalar_name`.

```mojo
def scalar_name(self, scalar: ScalarKind) -> String
```

## scalar_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/uform/mojo/encoding.md#UNKNOWN) when unrecognized. Calls `uform_scalar_from_name`.

```mojo
def scalar_from_name(self, name: StringSpan) -> ScalarKind
```

## mood_name

The engine's spelling of a mood, as [`PARKED`](https://www.unum.cloud/docs/uform/mojo/receivers-and-deferred-calls.md#PARKED) spells "parked". Calls `uform_mood_name`.

```mojo
def mood_name(self, mood: Mood) -> String
```

## mood_from_name

Reads a spelling back; [`PARKED`](https://www.unum.cloud/docs/uform/mojo/receivers-and-deferred-calls.md#PARKED) when unrecognized. Calls `uform_mood_from_name`.

```mojo
def mood_from_name(self, name: StringSpan) -> Mood
```

## cpu_class_name

The engine's spelling of a CPU class, as [`INTEL_HASWELL`](https://www.unum.cloud/docs/uform/mojo/executors.md#INTEL_HASWELL) spells "intel-haswell". Calls `uform_cpu_class_name`.

```mojo
def cpu_class_name(self, cpu_class: CPUClass) -> String
```

## cpu_class_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/uform/mojo/encoding.md#UNKNOWN) when unrecognized. Calls `uform_cpu_class_from_name`.

```mojo
def cpu_class_from_name(self, name: StringSpan) -> CPUClass
```

## gpu_class_name

The engine's spelling of a GPU class, as [`NVIDIA_HOPPER`](https://www.unum.cloud/docs/uform/mojo/executors.md#NVIDIA_HOPPER) spells "nvidia-hopper". Calls `uform_gpu_class_name`.

```mojo
def gpu_class_name(self, gpu_class: GPUClass) -> String
```

## gpu_class_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/uform/mojo/encoding.md#UNKNOWN) when unrecognized. Calls `uform_gpu_class_from_name`.

```mojo
def gpu_class_from_name(self, name: StringSpan) -> GPUClass
```

## modality_name

The engine's spelling of a modality, as [`TEXT`](https://www.unum.cloud/docs/uform/mojo/training.md#TEXT) spells "text". Calls `uform_modality_name`.

```mojo
def modality_name(self, modality: Modality) -> String
```

## modality_from_name

Reads a spelling back; [`TEXT`](https://www.unum.cloud/docs/uform/mojo/training.md#TEXT) when unrecognized. Calls `uform_modality_from_name`.

```mojo
def modality_from_name(self, name: StringSpan) -> Modality
```

## objective_name

The engine's spelling of an objective, as [`JOINT`](https://www.unum.cloud/docs/uform/mojo/training.md#JOINT) spells "joint". Calls `uform_objective_name`.

```mojo
def objective_name(self, objective: Objective) -> String
```

## objective_from_name

Reads a spelling back; [`MASKED`](https://www.unum.cloud/docs/uform/mojo/training.md#MASKED) when unrecognized. Calls `uform_objective_from_name`.

```mojo
def objective_from_name(self, name: StringSpan) -> Objective
```

## negatives_name

The engine's spelling of a negatives policy, as [`NAMED`](https://www.unum.cloud/docs/uform/mojo/training.md#NAMED) spells "named". Calls `uform_negatives_name`.

```mojo
def negatives_name(self, negatives: Negatives) -> String
```

## negatives_from_name

Reads a spelling back; [`AMBIENT`](https://www.unum.cloud/docs/uform/mojo/training.md#AMBIENT) when unrecognized. Calls `uform_negatives_from_name`.

```mojo
def negatives_from_name(self, name: StringSpan) -> Negatives
```

## multimem_tier_name

The engine's spelling of a multimem tier, as [`PEER_READ`](https://www.unum.cloud/docs/uform/mojo/executors.md#PEER_READ) spells "peer-read". Calls `uform_multimem_tier_name`.

```mojo
def multimem_tier_name(self, tier: MultimemTier) -> String
```

## multimem_tier_from_name

Reads a spelling back; [`SWITCH_REDUCED`](https://www.unum.cloud/docs/uform/mojo/executors.md#SWITCH_REDUCED) when unrecognized. Calls `uform_multimem_tier_from_name`.

```mojo
def multimem_tier_from_name(self, name: StringSpan) -> MultimemTier
```

