# Executors

> USearch for Mojo

One executor serves any number of indexes, and its residency must match the one their handles were built for.
`Executor(library)` owns nothing and runs every call handed it on the calling thread, whatever the handle's residency.
There is a constructor per C one, each taking every argument its own hardware has:

```mojo
var threads = Executor.for_ram(library, RamOptions.on(domains), threads=8)  # zero takes 7/8 of the cores
var shared = Executor.on_pool(library, fork_union_pool)                       # borrows a fu_pool_t
var streams = Executor.for_vram(library, VramOptions.on(devices))             # one host thread, a stream per device
var rings = Executor.for_nvme(library, threads=4)                             # one submission ring per thread
threads.drain(Mood.SPINNING)                                                # waits out the holding call, then keeps spinning
```

One call holds an executor at a time, while index handles stay freely concurrent, so threads that genuinely overlap take one executor apiece.
A second call finding the executor held finishes at once with `Status.CONTENDED`, and nothing queues.
A deferred call on a caller-exclusive pool runs on the pool's thread 0, so polling alone finishes it, and its progress handler and predicate run on the pool's threads; a single thread or a VRAM executor runs it at submission.

### Receivers & Deferred Calls

The receiver chooses where a verb runs and how it completes, and the verb stays the same.
The index runs it on the calling thread, `index.on(executor)` blocks on an executor, and `index.deferred(executor)` submits it there and answers a `Deferred`:

```mojo
index.search(queries, 10, arena)                               # the calling thread
index.on(executor).search(queries, 10, arena)                  # blocking, holding the executor until it returns
var call = index.deferred(executor).search(queries, 10, arena)  # Deferred[...], final once waited
```

`DenseIndexOn` and `DenseIndexDeferredOn` offer the same verbs with the same arguments.
The blocking verbs are written once, in the `DenseVerbs` trait both the index and `DenseIndexOn` conform to.
Constructors address no index yet, so no receiver offers them; the ones whose C structure names an executor take one.

A `Deferred` owns its outcome and outputs until the call is final, and borrows the index, the executor, the arena and every input it was handed, which Mojo keeps alive for as long as the `Deferred` is.

```mojo
var call = index.deferred(executor).search(queries, 10, arena)
if call.status() == Status.DEFERRED:
    pass  # other work
print(call.wait().query_keys(0)[0])  # the matches, read in place from your arena
```

Mojo has no runtime of its own to await on, so `wait` is the whole interface: it blocks in `usearch_outcome_wait` until the call is final, then answers the result or raises the failure, as many times as it is asked.
The result is the very `Matches` a blocking search answers, borrowing the same arena, and `status` reads the outcome without blocking.
A failure this binding catches before the call crosses is final at once, and arrives through the same `status` and `wait`.
Mojo destroys a value at its last use, and destroying an unfinished `Deferred` waits for it.
Calls depending on each other are ordered by waiting on the first before submitting the second.

`from usearch import DenseIndexOn, DenseIndexDeferredOn, DenseVerbs, …`

## DenseIndexOn

An index bound to the executor its verbs block on, as `index.on(executor)` answers it. Binding-only.

```mojo
struct DenseIndexOn[origin: ImmOrigin]
```

- `origin` (comptime): The index and the executor, which this receiver borrows.

- `index` `Pointer[DenseIndex, origin]`: The index every verb addresses.
- `executor` `Address`: The `usearch_executor_t` every verb runs on.

Conforms to: `Copyable`, `Deinitable`, `[DenseVerbs](#DenseVerbs)`, `ImplicitlyCopyable`, `Movable`

## __init__

Binds an index to an executor.

```mojo
def __init__(out self, index: Pointer[DenseIndex, origin], executor: Int)
```

- `index`: The index every verb addresses.
- `executor`: The `usearch_executor_t` every verb runs on.

## cursor

Opens a walk over every entry as stored, its pulls on the bound executor. Calls `usearch_dense_cursor_init`.

```mojo
def cursor(self) -> DenseCursor[origin]
```

```mojo
def cursor[starts_origin: ImmOrigin, //](
    self,
    starts: Span[Key, starts_origin]
) -> DenseCursor[origin]
```

Opens a walk from `starts`, its pulls on the bound executor. Calls `usearch_dense_cursor_init`.

- `starts_origin` (comptime): The start keys' origin, inferred from the argument.
- `starts`: The keys to walk from, the walk yielding their entries first.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the residency has no cursor, as VRAM does not.

## search_stream

Opens a resumable nearest-neighbor stream for one query, its pulls on the bound executor. Calls `usearch_dense_search_stream_init`.

```mojo
def search_stream[query_origin: ImmOrigin, //](
    self,
    query: RowsView[query_origin],
    config: DenseSearchStreamInitConfig = DenseSearchStreamInitConfig(expansion_factor=Int(0))
) -> DenseSearchStream[origin_of(origin, query_origin)]
```

- `query_origin` (comptime): The query row's origin, inferred from the argument.
- `query`: The single query row; a view of more rows has its first row read.
- `config`: The breadth of the candidates the walk explores.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`UNSUPPORTED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNSUPPORTED) while no residency implements the stream.

## DenseIndexDeferredOn

An index bound to the executor its verbs are submitted to, as `index.deferred(executor)` answers it: every verb answers a [`Deferred`](#Deferred) at once. Binding-only.

```mojo
struct DenseIndexDeferredOn[origin: ImmOrigin]
```

The verbs and their arguments are those of [`DenseVerbs`](#DenseVerbs), the arena borrowed as theirs is; only the
blocking receivers add the cursor and the search stream, whose every pull blocks.

- `origin` (comptime): The index and the executor, which this receiver borrows.

- `index` `Pointer[DenseIndex, origin]`: The index every verb addresses.
- `executor` `Address`: The `usearch_executor_t` every verb is submitted to.

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

## __init__

Binds an index to an executor.

```mojo
def __init__(out self, index: Pointer[DenseIndex, origin], executor: Int)
```

- `index`: The index every verb addresses.
- `executor`: The `usearch_executor_t` every verb is submitted to.

## reserve

Submits [`DenseVerbs.reserve`](#reserve). Calls `usearch_dense_reserve`.

```mojo
def reserve(self, capacity: Int) -> Deferred[_DenseReserveCall, origin]
```

## clear

Submits [`DenseVerbs.clear`](#clear). Calls `usearch_dense_clear`.

```mojo
def clear(self) -> Deferred[_DenseClearCall, origin]
```

## describe

Submits [`DenseVerbs.describe`](#describe). Calls `usearch_dense_describe`.

```mojo
def describe(self) -> Deferred[_DenseDescribeCall, origin]
```

## insert

Submits [`DenseVerbs.insert`](#insert); the keys, rows and telemetry slot stay borrowed until final. Calls `usearch_dense_insert`.

```mojo
def insert[keys_origin: ImmOrigin, vectors_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    keys: Span[Key, keys_origin],
    vectors: RowsView[vectors_origin],
    config: DenseInsertConfig[stats_origin] = DenseInsertConfig(expansion_factor=Int(0), stats=Optional())
) -> Deferred[_DenseInsertCall, origin_of(keys_origin, origin, stats_origin, vectors_origin)]
```

## refine

Submits [`DenseVerbs.refine`](#refine). Calls `usearch_dense_refine`.

```mojo
def refine[stats_origin: MutOrigin, //](
    self,
    config: DenseRefineConfig[stats_origin] = DenseRefineConfig(expansion_factor=Int(0), stats=Optional())
) -> Deferred[_DenseRefineCall, origin_of(origin, stats_origin)]
```

## health

Submits [`DenseVerbs.health`](#health). Calls `usearch_dense_health`.

```mojo
def health(self) -> Deferred[_DenseHealthCall, origin]
```

## absorb

Submits [`DenseVerbs.absorb`](#absorb); the donors are owned by the call. Calls `usearch_dense_absorb`.

```mojo
def absorb(self, var donors: List[DenseIndex]) -> Deferred[_DenseAbsorbCall, origin]
```

## split

Submits [`DenseVerbs.split`](#split); the receivers stay borrowed until final. Calls `usearch_dense_split`.

```mojo
def split(
    self,
    receivers: List[DenseIndex],
    seed: UInt64 = UInt64(0)
) -> Deferred[_DenseSplitCall, origin_of(origin, receivers)]
```

## sample

Submits [`DenseVerbs.sample`](#sample); the shown keys, focus and arena stay borrowed until final. Calls `usearch_dense_sample`.

```mojo
def sample[shown_origin: ImmOrigin, coordinates_origin: ImmOrigin, focus_origin: ImmOrigin, //](
    self,
    wanted: Int,
    mut arena: Arena,
    config: DenseSampleConfig[shown_origin, coordinates_origin, focus_origin] = DenseSampleConfig(shown=Span(), shown_coordinates=Span(), focus=Span(), seed=UInt64(0))
) -> Deferred[_DenseSampleCall[origin_of(arena)], origin_of(coordinates_origin, focus_origin, origin, shown_origin)]
```

## search

Submits [`DenseVerbs.search`](#search); the queries, telemetry slot and arena stay borrowed until final. Calls `usearch_dense_search`.

```mojo
def search[queries_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    queries: RowsView[queries_origin],
    wanted: Int,
    mut arena: Arena,
    config: DenseSearchConfig[stats_origin] = DenseSearchConfig(expansion_factor=Int(0), traversal=Traversal.WALK, predicate=Int(0), predicate_state=Int(0), stats=Optional())
) -> Deferred[_DenseSearchCall[origin_of(arena)], origin_of(origin, queries_origin, stats_origin)]
```

## count

Submits [`DenseVerbs.count`](#count). Calls `usearch_dense_count`.

```mojo
def count(self, key: Key) -> Deferred[_DenseCountCall, origin]
```

## get

Submits [`DenseVerbs.get`](#get); the arena stays borrowed until final. Calls `usearch_dense_get`.

```mojo
def get[dtype: DType](
    self,
    key: Key,
    mut arena: Arena,
    scalar: ScalarKind = ScalarKind.of[dtype]()
) -> Deferred[_DenseGetCall[dtype, origin_of(arena)], origin]
```

## save

Submits [`DenseVerbs.save`](#save); the path stays borrowed until final. Calls `usearch_dense_save`.

```mojo
def save[path_origin: ImmOrigin, //](
    self,
    path: StringSpan[path_origin]
) -> Deferred[_DenseSaveCall, origin_of(origin, path_origin)]
```

## save_buffer

Submits [`DenseVerbs.save_buffer`](#save_buffer); the arena stays borrowed until final. Calls `usearch_dense_save_buffer`.

```mojo
def save_buffer(self, mut arena: Arena) -> Deferred[_DenseSaveBufferCall[origin_of(arena)], origin]
```

## multiply

Submits [`DenseVerbs.multiply`](#multiply); the rows, telemetry slot and arena stay borrowed until final. Calls `usearch_dense_multiply`.

```mojo
def multiply[left_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    left: RowsView[left_origin],
    mut arena: Arena,
    config: DenseMultiplyConfig[stats_origin] = DenseMultiplyConfig(wanted=Int(0), expansion_factor=Int(0), stats=Optional())
) -> Deferred[_DenseMultiplyCall[origin_of(arena)], origin_of(left_origin, origin, stats_origin)]
```

## attend

Submits [`DenseVerbs.attend`](#attend); the queries, carry, telemetry slot and arena stay borrowed until final, and the lookup state must outlive the call too. Calls `usearch_dense_attend`.

```mojo
def attend[queries_origin: ImmOrigin, carry_origin: MutOrigin, stats_origin: MutOrigin, //, dtype: DType](
    self,
    queries: RowsView[queries_origin],
    value_lookup: def(Int, Pointer[Key, ImmUntrackedOrigin], UInt, ScalarKind, UInt, Pointer[Int, MutAnyOrigin]) abi("C") thin -> None,
    value_lookup_state: Int,
    mut arena: Arena,
    config: DenseAttendConfig[carry_origin, stats_origin] = DenseAttendConfig(head_count=Int(0), carry=Span(), expansion_factor=Int(0), score_scale=Float32("0"), stats=Optional())
) -> Deferred[_DenseAttendCall[dtype, origin_of(arena)], origin_of(carry_origin, origin, queries_origin, stats_origin)]
```

## maxsim

Submits [`DenseVerbs.maxsim`](#maxsim); the queries, telemetry slot and arena stay borrowed until final. Calls `usearch_dense_maxsim`.

```mojo
def maxsim[queries_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    queries: RowsView[queries_origin],
    rows_per_query: Int,
    wanted: Int,
    mut arena: Arena,
    config: DenseMaxsimConfig[stats_origin] = DenseMaxsimConfig(expansion_factor=Int(0), stats=Optional())
) -> Deferred[_DenseMaxsimCall[origin_of(arena)], origin_of(origin, queries_origin, stats_origin)]
```

## DenseVerbs

The verbs every blocking receiver offers - the index on the calling thread, and `index.on(executor)` on an executor - each written once over the receiver's `_route`.

```mojo
trait DenseVerbs
```

## reserve

Reserves capacity for a number of incoming vectors ahead of insertion. Calls `usearch_dense_reserve`.

```mojo
def reserve(self, capacity: Int)
```

- `capacity`: The desired total capacity, including the current size.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the reservation cannot be satisfied, or contradicts a frozen geometry.

## clear

Erases every entry, keeping the reserved capacity and the frozen geometry. Calls `usearch_dense_clear`.

```mojo
def clear(self)
```

Never invoked concurrently with any other verb on the same handle.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`READ_ONLY`](https://www.unum.cloud/docs/usearch/mojo/errors.md#READ_ONLY) if the handle serves its checkpoint in place.

## describe

Reports the frozen metadata and the current counters in one call. Calls `usearch_dense_describe`.

```mojo
def describe(self) -> DenseIndexDescription
```

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the query.

## insert

Adds a run of vectors under their keys - the native batch operation. Calls `usearch_dense_insert`.

```mojo
def insert[keys_origin: ImmOrigin, vectors_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    keys: Span[Key, keys_origin],
    vectors: RowsView[vectors_origin],
    config: DenseInsertConfig[stats_origin] = DenseInsertConfig(expansion_factor=Int(0), stats=Optional())
)
```

A batch is all-or-nothing, because this binding installs no progress handler: every
fallible step runs before the first entry identity is claimed, so a rejected batch leaves
the index untouched and publishes no entry.

- `keys_origin` (comptime): The key run's origin, inferred from the argument.
- `vectors_origin` (comptime): The row storage's origin, inferred with it.
- `stats_origin` (comptime): The lent telemetry slot's origin, inferred with it.
- `keys`: One key per row of `vectors`; keys need not be unique.
- `vectors`: The rows to insert, converted on ingest to the stored type.
- `config`: The breadth of the candidates and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the shapes disagree or the handle is read-only.

## refine

Re-selects every entry's neighbors against the finished graph. Calls `usearch_dense_refine`.

```mojo
def refine[stats_origin: MutOrigin, //](
    self,
    config: DenseRefineConfig[stats_origin] = DenseRefineConfig(expansion_factor=Int(0), stats=Optional())
) -> DenseRefineReport
```

A build step rather than a repair: a cheap insertion pass followed by one refinement
reaches a better graph, in less total time, than a single expensive insertion pass - so a
wide expansion factor belongs here rather than in [`insert`](#insert). Searches may run throughout;
insertions may not.

- `stats_origin` (comptime): The lent telemetry slot's origin, inferred from the argument.
- `config`: The breadth of the candidates the re-selection walk explores, and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`READ_ONLY`](https://www.unum.cloud/docs/usearch/mojo/errors.md#READ_ONLY) if the handle serves its checkpoint in place.

## health

Audits how much of the graph a search reaches from its landmarks. Calls `usearch_dense_health`.

```mojo
def health(self) -> DenseReachability
```

Read-only, so concurrent insertions merely leave fresh entries unaudited.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the audit.

## absorb

Absorbs every donor into this index, keeping their graphs rather than re-inserting their vectors. Calls `usearch_dense_absorb`.

```mojo
def absorb(self, var donors: List[DenseIndex]) -> DenseRefineReport
```

Each donor the engine consumes is emptied here, so dropping the list releases only the
donors a stopped absorb left standing.

- `donors` (var): The handles to absorb, consumed by the call.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`CONFIG_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#CONFIG_MISMATCH) for a donor of another residency, scalar, metric or geometry, or with [`READ_ONLY`](https://www.unum.cloud/docs/usearch/mojo/errors.md#READ_ONLY) if the handle serves its checkpoint in place.

## split

Splits this index into the receivers, the inverse of [`absorb`](#absorb): graph-local parts keeping their edges, one per receiver, leaving this index empty but live. Calls `usearch_dense_split`.

```mojo
def split(self, receivers: List[DenseIndex], seed: UInt64 = UInt64(0)) -> DenseRefineReport
```

- `receivers`: Two or more empty handles of this index's residency, scalar, class, metric, geometry and shard count, each receiving one part.
- `seed`: Picks the part roots; equal seeds over an unchanged index split equally.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`CONFIG_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#CONFIG_MISMATCH) for a mismatched or non-empty receiver, in which case nothing moves, or with [`READ_ONLY`](https://www.unum.cloud/docs/usearch/mojo/errors.md#READ_ONLY) if the handle serves its checkpoint in place.

## sample

Draws up to `wanted` keys around `config.focus`, or across the whole index, each hanging from a shown or earlier draw and placed in three dimensions beside the shown ones. Calls `usearch_dense_sample`.

```mojo
def sample[shown_origin: ImmOrigin, coordinates_origin: ImmOrigin, focus_origin: ImmOrigin, //](
    self,
    wanted: Int,
    mut arena: Arena,
    config: DenseSampleConfig[shown_origin, coordinates_origin, focus_origin] = DenseSampleConfig(shown=Span(), shown_coordinates=Span(), focus=Span(), seed=UInt64(0))
) -> DenseDraws[origin_of(arena)]
```

A larger `wanted` draws a superset, so a view grows one connected sample as it zooms. Only
RAM samples yet.

- `shown_origin` (comptime): The shown keys' origin, inferred from the config.
- `coordinates_origin` (comptime): Their coordinates' origin, inferred with it.
- `focus_origin` (comptime): The focus keys' origin, inferred with it.
- `wanted`: The upper bound on draws.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `config`: The shown keys and their coordinates, the focus and the seed.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`SHAPE_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#SHAPE_MISMATCH) unless there are three coordinates per shown key, or [`UNSUPPORTED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#UNSUPPORTED) off RAM.

## search

Performs k-approximate nearest-neighbor search for a batch of queries, writing the matches in a lent arena. Calls `usearch_dense_search`.

```mojo
def search[queries_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    queries: RowsView[queries_origin],
    wanted: Int,
    mut arena: Arena,
    config: DenseSearchConfig[stats_origin] = DenseSearchConfig(expansion_factor=Int(0), traversal=Traversal.WALK, predicate=Int(0), predicate_state=Int(0), stats=Optional())
) -> Matches[origin_of(arena)]
```

Never writes to the graph, so any number of these may overlap with concurrent insertions.

- `queries_origin` (comptime): The query rows' origin, inferred from the argument.
- `stats_origin` (comptime): The lent telemetry slot's origin, inferred with it.
- `queries`: The query rows, one per search.
- `wanted`: Matches per query - the "k"; zero lands only the counts.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `config`: The breadth of the candidates, the predicate, and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the shapes disagree, or a predicate is passed to a VRAM handle.

## count

How many entries the index stores under one key. Calls `usearch_dense_count`.

```mojo
def count(self, key: Key) -> Int
```

- `key`: The key whose entries are counted.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the query.

## get

Exports every vector stored under one key into a lent arena, one row per entry, in insertion order. Calls `usearch_dense_get`.

```mojo
def get[dtype: DType](
    self,
    key: Key,
    mut arena: Arena,
    scalar: ScalarKind = ScalarKind.of[dtype]()
) -> DenseVectors[dtype, origin_of(arena)]
```

- `dtype` (comptime): The element type the rows are read as, which `scalar` must store whole.
- `key`: The key whose entries are exported.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `scalar`: The scalar type to export as, converted from storage where it differs; the kind `dtype` stores by default.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`SHAPE_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#SHAPE_MISMATCH) if `dtype` cannot hold `scalar`, or if the engine refuses the export.

## save

Writes a checkpoint, the path extension picking the layout. Calls `usearch_dense_save`.

```mojo
def save[path_origin: ImmOrigin, //](self, path: StringSpan[path_origin])
```

A `.safegraphs` path is one monolith; a `.safegraphs.json` path is a manifest naming one
monolith per shard. Demands a mutation-free window; concurrent readers keep searching
throughout. A failed save leaves a file without its header, which every reader rejects, and
that leftover is the caller's to remove.

- `path_origin` (comptime): The path bytes' origin, inferred from the argument.
- `path`: Destination path, whose extension picks the layout.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the destination cannot be written.

## save_buffer

Serializes the index as one monolith into a lent arena - the same bytes the path-taking sibling writes. Calls `usearch_dense_save_buffer`.

```mojo
def save_buffer(self, mut arena: Arena) -> Monolith[origin_of(arena)]
```

- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the engine refuses the write.

## multiply

Approximate sparse product of a run of rows against the indexed vectors, into a lent arena. Calls `usearch_dense_multiply`.

```mojo
def multiply[left_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    left: RowsView[left_origin],
    mut arena: Arena,
    config: DenseMultiplyConfig[stats_origin] = DenseMultiplyConfig(wanted=Int(0), expansion_factor=Int(0), stats=Optional())
) -> DenseProducts[origin_of(arena)]
```

Reports every pair the traversal scored instead of only the nearest, in traversal order
rather than sorted, and with no duplicates. Cost is roughly
`rows x expansion x connectivity x dimensions`, sublinear in the indexed entries, which is the
whole point of reading a product off a graph. Runs on [`DenseMetric.INNER`](https://www.unum.cloud/docs/usearch/mojo/metrics.md#INNER) alone.

- `left_origin` (comptime): The left-hand rows' origin, inferred from the argument.
- `stats_origin` (comptime): The lent telemetry slot's origin, inferred with it.
- `left`: The left-hand rows.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `config`: The pairs kept per row, the breadth of the candidates, and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`CONFIG_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#CONFIG_MISMATCH) if the graph was frozen under a distance kind.

## attend

Softmax attention of a run of query heads over every indexed key their graph walks score, written in a lent arena. Calls `usearch_dense_attend`.

```mojo
def attend[queries_origin: ImmOrigin, carry_origin: MutOrigin, stats_origin: MutOrigin, //, dtype: DType](
    self,
    queries: RowsView[queries_origin],
    value_lookup: def(Int, Pointer[Key, ImmUntrackedOrigin], UInt, ScalarKind, UInt, Pointer[Int, MutAnyOrigin]) abi("C") thin -> None,
    value_lookup_state: Int,
    mut arena: Arena,
    config: DenseAttendConfig[carry_origin, stats_origin] = DenseAttendConfig(head_count=Int(0), carry=Span(), expansion_factor=Int(0), score_scale=Float32("0"), stats=Optional())
) -> DenseVectors[dtype, origin_of(arena)]
```

Every key a walk scores folds into each head's running maximum, partition, and weighted
value sum, as Flash Attention folds key tiles, with no top-k cut: the long tail the walk
scores is what brings the result toward exact dense attention. The outputs come back
already divided by the partition.

Row `t · head_count + h` of `queries`, the outputs, and `carry` is head `h` of token `t`. One
index holds one layer's one key-value head, so the `head_count` query heads of grouped-query
attention share its keys and one walk per token.

The index stores no values: `value_lookup` resolves the keys of every scored batch to their
value rows, so only keys a walk scores are ever resolved. `carry` is the softmax's `m` and
`l`, one [`DenseSoftmaxState`](https://www.unum.cloud/docs/usearch/mojo/linear-algebra.md#DenseSoftmaxState) per query row, lent by the caller: supplying it folds this branch
into another over the same queries, such as the recent window kept out of the index, by
partial-softmax rescaling.

- `queries_origin` (comptime): The query rows' origin, inferred from the argument.
- `carry_origin` (comptime): The softmax states' origin, inferred with it where any are supplied.
- `stats_origin` (comptime): The lent telemetry slot's origin, inferred with it.
- `dtype` (comptime): The element type the attended rows land as, which must name a scalar kind.
- `queries`: The query rows, `head_count` per token.
- `value_lookup`: Resolves every scored batch of keys to their value rows - a host function on RAM, and a device one on VRAM.
- `value_lookup_state`: The opaque state forwarded into every `value_lookup` call.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `config`: The heads per token, the carry, the breadth of the candidates, the logit scale, and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`SHAPE_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#SHAPE_MISMATCH) if `dtype` names no scalar kind, `head_count` does not divide the rows, the carry holds fewer states than there are rows, or a lookup yields a null row; with [`CONFIG_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#CONFIG_MISMATCH) if the graph was frozen under a distance kind.

## maxsim

Late-interaction scoring: every query row takes its best match within a key, and those maxima sum to that key's score, written in a lent arena. Calls `usearch_dense_maxsim`.

```mojo
def maxsim[queries_origin: ImmOrigin, stats_origin: MutOrigin, //](
    self,
    queries: RowsView[queries_origin],
    rows_per_query: Int,
    wanted: Int,
    mut arena: Arena,
    config: DenseMaxsimConfig[stats_origin] = DenseMaxsimConfig(expansion_factor=Int(0), stats=Optional())
) -> DenseProducts[origin_of(arena)]
```

This is what `values_per_key` above one exists for. A document is one key holding its token
rows, and the walk stays over individual tokens under a plain inner product. Approximate in
the usual direction: a key can score below its exact value but never above it.

- `queries_origin` (comptime): The query rows' origin, inferred from the argument.
- `stats_origin` (comptime): The lent telemetry slot's origin, inferred with it.
- `queries`: The token rows of every query, laid end to end.
- `rows_per_query`: Rows in every query; uniform, so ColBERT's padding applies as is.
- `wanted`: Keys per query - the "k" over documents rather than rows; zero keeps every key scored.
- `arena` (mut): The arena to rewind and refill, which the result borrows; a failed call leaves it valid.
- `config`: The breadth of the candidates and the telemetry slot.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) with [`SHAPE_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#SHAPE_MISMATCH) if `rows_per_query` does not divide the rows; with [`CONFIG_MISMATCH`](https://www.unum.cloud/docs/usearch/mojo/errors.md#CONFIG_MISMATCH) if the graph was frozen under a distance kind.

## Mood

What an executor does with its threads or streams once it goes idle - `usearch_mood_t`.

```mojo
struct Mood
```

- `PARKED` = `Mood(Int32(1))`: Idle threads sleep; the next call pays a wake-up.
- `SPINNING` = `Mood(Int32(2))`: Idle threads stay hot, trading power for the next call's latency.
- `code` `c_int`: The raw `usearch_mood_t` value the ABI exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## Executor

The threads or streams a verb runs on, freed once it and every VRAM arena it made go out of scope.

```mojo
struct Executor
```

`Executor(library)` owns nothing: every verb handed it runs on the calling thread -
single-threaded on RAM, on the handle's device and default stream on VRAM. The spawning
constructors fix a kind that must match the residency of every handle they drive. Calls on one
executor start in submission order, so threads that genuinely overlap take one apiece.

- `library` `Library`: The loaded engine, held so its symbol table outlives every call made through the handle.
- `address` `Address`: The opaque `usearch_executor_t` every verb hands back to the engine; `NULL_ADDRESS` runs inline.
- `residency` `Residency`: Where the arenas it makes live; the caller-thread executor makes host pages.

Conforms to: `Deinitable`, `Movable`

## __init__

The caller-thread executor, which every verb accepts whatever the handle's residency.

```mojo
def __init__(out self, library: Library)
```

```mojo
def __init__(out self, *, library: Library, address: Int, residency: Residency)
```

Adopts a handle that is already spawned, which is how the factories hand one back.

- `library`: The loaded engine, kept so the shared object stays mapped.
- `address`: A `usearch_executor_t` whose lifetime this executor takes over.
- `residency`: The residency of the handles it drives, which places the arenas it makes.

## for_ram

Spawns host workers for RAM-resident indexes. Calls `usearch_executor_for_ram`.

```mojo
def for_ram[ram_origin: ImmOrigin, //](
    library: Library,
    ram: RamOptions[ram_origin] = RamOptions(),
    threads: Int = Int(0),
    deferred_limit: Int = Int(0)
) -> Self
```

Passing the very options the indexes were built with is what makes compute and memory
domains agree, leaving no second place to name hardware.

- `ram_origin` (comptime): The options' borrowed node-id array, inferred from the argument.
- `library`: The loaded engine, kept so the shared object stays mapped.
- `ram`: The same options the indexes were initialized with; copied, not borrowed.
- `threads`: Worker threads; zero takes 7/8 of the cores those domains carry.
- `deferred_limit`: Deferred calls it tracks at once, sizing its deferred table; zero takes a default.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the domains cannot be resolved or the OS refuses the threads.

## on_pool

Schedules onto a borrowed ForkUnion pool, so several libraries share one set of threads. Calls `usearch_executor_on_pool`.

```mojo
def on_pool[ram_origin: ImmOrigin, //](
    library: Library,
    pool: Int,
    ram: RamOptions[ram_origin] = RamOptions(),
    deferred_limit: Int = Int(0)
) -> Self
```

- `ram_origin` (comptime): The options' borrowed node-id array, inferred from the argument.
- `library`: The loaded engine, kept so the shared object stays mapped.
- `pool`: A live ForkUnion `fu_pool_t`, which must outlive the executor.
- `ram`: The same options the indexes were initialized with; copied, not borrowed.
- `deferred_limit`: Deferred calls it tracks at once, sizing its deferred table; zero takes a default.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if the pool or the domains are refused.

## for_nvme

Spawns host workers for NVMe-resident indexes, one submission ring apiece. Calls `usearch_executor_for_nvme`.

```mojo
def for_nvme[nvme_origin: ImmOrigin, //](
    library: Library,
    nvme: NvmeOptions[nvme_origin] = NvmeOptions(),
    threads: Int = Int(0),
    deferred_limit: Int = Int(0)
) -> Self
```

One ring per thread is what keeps submission lock-free: a thread owns its queue outright,
so an external-memory walk never coordinates with a sibling to issue a read.

- `nvme_origin` (comptime): The options' borrowed path array, inferred from the argument.
- `library`: The loaded engine, kept so the shared object stays mapped.
- `nvme`: The same options the indexes were initialized with; copied, not borrowed.
- `threads`: Worker threads; zero derives from the devices' queue capabilities.
- `deferred_limit`: Deferred calls it tracks at once, sizing its deferred table; zero takes a default.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if a path cannot be opened or the OS refuses the threads.

## for_vram

Opens one submission stream on every named device, all driven by the calling thread. Calls `usearch_executor_for_vram`.

```mojo
def for_vram[vram_origin: ImmOrigin, //](
    library: Library,
    vram: VramOptions[vram_origin] = VramOptions(),
    streams: Int = Int(0),
    scratch_limit: Int = Int(0),
    deferred_limit: Int = Int(0)
) -> Self
```

One stream per device is the whole design: a single host thread keeps every device fed, and
adding host threads would buy nothing, which is why this constructor takes no thread count.

- `vram_origin` (comptime): The options' borrowed ordinal array, inferred from the argument.
- `library`: The loaded engine, kept so the shared object stays mapped.
- `vram`: The same options the indexes were initialized with; copied, not borrowed.
- `streams`: Borrowed CUDA streams, one per device in `vram` order; `NULL_ADDRESS` creates its own.
- `scratch_limit`: Ceiling on scratch bytes per device; zero lets scratch grow as geometry asks.
- `deferred_limit`: Deferred calls it tracks at once, sizing its deferred table; zero takes a default.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) if a device cannot be selected or its memory cannot be claimed.

## drain

Waits for every call submitted before the drain, then adopts `mood` whenever it next idles. Calls `usearch_executor_drain`.

```mojo
def drain(self, mood: Mood = Mood.PARKED)
```

An executor without threads of its own holds a deferred call until its wait, the next drain
or blocking call, or the free of a handle it names, so this runs every call it still holds.

- `mood`: What the threads or streams do once idle; the last drain wins.

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) for a failure of the executor itself, such as a lost device - never one of a drained call, which reports through its own outcome.

## Deferred

A call submitted to an executor, which owns its outcome and outputs until it is final. Binding-only.

```mojo
struct Deferred[C: Call, origin: ImmOrigin]
```

[`status`](#status) reads [`DEFERRED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEFERRED) until then, without blocking, and [`wait`](#wait) blocks until the call is
final and answers its result or raises its failure, as many times as it is asked. The result is
the view a blocking call answers, borrowing the same arena. Dropping an unfinished one waits the
same way, so nothing the engine still writes is ever freed under it. The origins keep the index,
the executor, the arena and every borrowed input alive for as long as this is.

An executor without threads of its own holds a deferred call until its wait, its executor's
next drain or blocking call, or the free of a handle it names, so a [`wait`](#wait) - or the last use of
the [`Deferred`](#Deferred), which Mojo destroys at once - runs it there.

- `C` (comptime): The verb's crossing, which names the result.
- `origin` (comptime): The union of everything the call borrows.

- `library` `Library`: The loaded engine, held so the wait can still reach `usearch_outcome_wait`.
- `slots` `OwnedPointer[CallSlots[C.Outputs]]`: The outcome and scalar outputs the engine writes, on the heap since they outlive the verb.
- `call` `Optional[C]`: What the call lends the engine, until a wait concludes it.
- `answer` `Optional[C.Result]`: The result, once a wait found the call succeeded.
- `failure` `Optional[Error]`: The failure, once a wait found the call failed.
- `generation` `Int`: The stamp `served` answered at submission, so a result waited on late still reads as stale.

Conforms to: `Deinitable`, `Movable`

## __init__

Submits `call` deferred, on `executor`, against `index`.

```mojo
def __init__(out self, library: Library, var call: C, index: Int, executor: Int)
```

- `library`: The loaded engine the call crosses into.
- `call` (var): The verb's crossing, owned until the call is final.
- `index`: The handle the call names, or `NULL_ADDRESS` for one that names none.
- `executor`: The executor the call is submitted to.

## __deinit__

Waits until the call is final, then frees what it lent. Calls `usearch_outcome_wait`.

```mojo
def __deinit__(deinit self)
```

## status

[`DEFERRED`](https://www.unum.cloud/docs/usearch/mojo/errors.md#DEFERRED) until the call is final, then its final status; never blocks. Calls `usearch_outcome_status`.

```mojo
def status(self) -> Status
```

## wait

Blocks until the call is final, then answers its result or raises its failure, every time it is asked. Calls `usearch_outcome_wait`.

```mojo
def wait(mut self) -> ref[self] C.Result
```

Raises: [`Error`](https://www.unum.cloud/docs/usearch/mojo/errors.md#Error) carrying the call's failure, whether the engine or the binding refused it.