# Executors

> UForm for Python

`uform.Executor.for_ram(threads=0, *, memory_domains=None, cpu_class=None)` creates an executor of host threads, and `uform.Executor.for_vram(devices=None, *, scratch_limit=0, gpu_class=None)` opens one stream per device.
A device is named by its position in `uform.gpu_devices()`, which lists every GPU the process can drive as a `uform.GPUDevice`, NVIDIA devices first, then AMD.
A `uform.CPUClass` or `uform.GPUClass` pin dispatches as that class, and `None` derives the hardware's own.
`uform.Executor.on_pool(pool)` mirrors the C verb that borrows a ForkUnion pool, and raises `UnsupportedError` until borrowing is designed.
An executor runs one call at a time, and a call finding another one holding it raises `ContendedError` once waited for. A deferred call on the executor's own threads finishes while Python only awaits it, and its progress callbacks run on those threads, holding the GIL while they do.
`executor.drain(uform.Mood.PARKED)` waits until no call holds the executor and its devices are idle, then applies the mood.
In a `with` block, it waits for its calls and closes on exit.

`import uform`

`from uform import GPUDevice, Executor, MeshOptions, …`

## CPUClass

The CPU families dispatch picks from, valued as `uform_cpu_class_t`; a RAM placement may pin one.

```python
class CPUClass(IntEnum)
```

- `SERIAL` = `1`
- `INTEL_HASWELL` = `2`
- `INTEL_SIERRA` = `3`
- `INTEL_SKYLAKE` = `4`
- `INTEL_ICELAKE` = `5`
- `AMD_GENOA` = `6`
- `INTEL_SAPPHIRE` = `7`
- `INTEL_GRANITE` = `8`
- `INTEL_DIAMOND` = `9`
- `AWS_G2` = `10`
- `APPLE_M2` = `11`
- `APPLE_M4` = `12`
- `AWS_G5` = `13`
- `NVIDIA_VERA` = `14`
- `ALIBABA_C930` = `15`
- `WASM32_V128` = `16`
- `WASM64_EXTENDED` = `17`
- `MONOVERSIONED` = `18`

## GPUClass

The GPU families dispatch picks from, valued as `uform_gpu_class_t`; a VRAM placement may pin one.

```python
class GPUClass(IntEnum)
```

- `NVIDIA_AMPERE` = `1`
- `NVIDIA_ADA` = `2`
- `NVIDIA_HOPPER` = `3`
- `NVIDIA_BLACKWELL` = `4`
- `NVIDIA_BLACKWELLRTX` = `5`
- `NVIDIA_RUBIN` = `6`
- `AMD_CDNA3` = `7`
- `AMD_CDNA4` = `8`
- `AMD_CDNA5` = `9`
- `APPLE_METAL7` = `10`
- `APPLE_METAL9` = `11`
- `APPLE_METAL10` = `12`

## GPUVendor

The vendor whose runtime drives a GPU, valued as `uform_gpu_vendor_t`.

```python
class GPUVendor(IntEnum)
```

- `NVIDIA` = `1`
- `AMD` = `2`
- `APPLE` = `3`

## MultimemTier

How a mesh's NVLink domains reduce, valued as `uform_multimem_tier_t`.

```python
class MultimemTier(IntEnum)
```

- `SWITCH_REDUCED` = `0`
- `PEER_READ` = `1`

## GPUDevice

One GPU this process can drive, its position in `gpu_devices()` being its ordinal.

```python
class GPUDevice(structseq[Any], tuple[GPUVendor, int, GPUClass | None, int, int, str])
```

## vendor

The vendor whose runtime drives the device.

```python
vendor: GPUVendor
```

## vendor_ordinal

The device's ordinal in its vendor's runtime, as nvidia-smi or rocm-smi list it.

```python
vendor_ordinal: int
```

## gpu_class

The class whose kernels run on it, or None.

```python
gpu_class: GPUClass | None
```

## compute_units

Streaming multiprocessors or compute units.

```python
compute_units: int
```

## memory_bytes

Device memory in bytes.

```python
memory_bytes: int
```

## name

The vendor's own name for the device.

```python
name: str
```

## Executor

The threads or streams a verb runs on, shared across models and named by [`on`](https://www.unum.cloud/docs/uform/python/training.md#on) and [`deferred`](https://www.unum.cloud/docs/uform/python/training.md#deferred).

```python
class Executor
```

## for_ram

Spawns host threads for RAM-resident models.

```python
@classmethod
def for_ram(
    threads: int = 0,
    *,
    memory_domains: Sequence[int] | None = None,
    deferred_limit: int = 0,
    cpu_class: CPUClass | None = None,
) -> Executor
```

Calls `uform_executor_for_ram`.

## on_pool

Borrows a ForkUnion pool; raises [`UnsupportedError`](https://www.unum.cloud/docs/uform/python/errors.md#UnsupportedError) until borrowing is designed.

```python
@classmethod
def on_pool(
    pool: int,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    deferred_limit: int = 0,
    cpu_class: CPUClass | None = None,
) -> Executor
```

Calls `uform_executor_on_pool`.

## for_vram

Opens one submission stream on every named device.

```python
@classmethod
def for_vram(
    devices: Sequence[int] | None = None,
    *,
    scratch_limit: int = 0,
    deferred_limit: int = 0,
    gpu_class: GPUClass | None = None,
    memory_domains: Sequence[int] | None = None,
    cpu_class: CPUClass | None = None,
) -> Executor
```

Calls `uform_executor_for_vram`.

## drain

Waits for every call submitted before it, then sets the idle mood.

```python
def drain(mood: Mood = ...) -> None
```

Calls `uform_executor_drain`.

## __exit__

Closes it once its calls finish, or leaves that to its last live GPU arena.

```python
def __exit__(
    kind: type[BaseException] | None,
    value: BaseException | None,
    traceback: TracebackType | None,
    /,
) -> None
```

Calls `uform_executor_free`.

## MeshOptions

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

```python
class MeshOptions
```

## MeshOptions

```python
MeshOptions(
    *,
    host_domain_index: int = 0,
    host_domain_count: int = 0,
    gpus_per_multimem_domain: int = 0,
    directory: _PathLike | None = None,
    job: str | None = None,
    timeout_seconds: float = 0.0,
)
```

## host_domain_index

```python
host_domain_index: Final[int]
```

## host_domain_count

```python
host_domain_count: Final[int]
```

## gpus_per_multimem_domain

```python
gpus_per_multimem_domain: Final[int]
```

## directory

```python
directory: Final[_PathLike | None]
```

## job

```python
job: Final[str | None]
```

## timeout_seconds

```python
timeout_seconds: Final[float]
```

## MeshDescription

What a mesh reports about itself, as `uform_mesh_description_t` holds it.

```python
class MeshDescription(structseq[Any], tuple[int, int, int, int, int, MultimemTier, GPUClass | None])
```

## gpus_per_host_domain

GPUs one process drives.

```python
gpus_per_host_domain: int
```

## gpus_per_multimem_domain

GPUs one NVLink domain spans.

```python
gpus_per_multimem_domain: int
```

## gpus_per_colocated_domain

GPUs in the whole run.

```python
gpus_per_colocated_domain: int
```

## host_domain_index

This process's index among the run's processes.

```python
host_domain_index: int
```

## first_gpu_index

The run-wide index of this process's first GPU.

```python
first_gpu_index: int
```

## multimem_tier

How its NVLink domains reduce.

```python
multimem_tier: MultimemTier
```

## gpu_class

The class every GPU of the run dispatches as, or None.

```python
gpu_class: GPUClass | None
```

## Mesh

One process's place among the processes of a run, borrowed by every trainer.

```python
class Mesh
```

## bootstrap

Joins this process to the run's mesh.

```python
@classmethod
def bootstrap(
    executor: Executor,
    options: MeshOptions | None,
    /,
) -> Mesh
```

Calls `uform_mesh_bootstrap`.

## describe

The mesh's shape and this process's place in it.

```python
def describe() -> MeshDescription
```

Calls `uform_mesh_describe`.

## capabilities_compiled

The hardware capabilities this binary was compiled with.

```python
def capabilities_compiled() -> str
```

Calls `uform_capabilities_compiled`.

## capabilities_available

The hardware capabilities this machine offers at runtime.

```python
def capabilities_available() -> str
```

Calls `uform_capabilities_available`.

## gpu_devices

Every GPU this process can drive, a device's position being its ordinal.

```python
def gpu_devices() -> tuple[GPUDevice, ...]
```

Calls `uform_gpu_devices`.