# Executors

> USearch for Swift

An index says where its payload lives; an `Executor` says who walks it.
One executor serves any number of handles, so several categories of index share one machine's cores or devices instead of each claiming a private set.
Its kind is fixed by the factory that spawned it and must match every handle it drives; a mismatch reports `device`.

```swift
let hostThreads = try Executor.forRam(memoryDomains: [0, 1], threads: 0)
let submissionRings = try Executor.forNvme(paths: ["/mnt/nvme0"], threads: 8)
let deviceStreams = try Executor.forVram(devices: [0, 1], streams: nil, scratchLimit: 1 << 30)
```

Each factory takes every argument its C constructor has, and only those.
`forVram` can borrow your CUDA streams, one per device, or cap per-device scratch.
A thread count of zero derives from the hardware: 7/8 of the cores those memory domains carry, since full occupancy starves the ordered publication path, and for NVMe the devices' queue capabilities.
`forVram` takes no thread count at all: one host thread drives one stream per device, so there is no count to name.

One call holds an executor at a time, and index handles stay freely shareable.
`Executor.onPool(memoryDomains:cpuClass:pool:)` borrows an existing ForkUnion pool instead of spawning threads, and `drain(mood:)` waits until no call holds the executor and picks whether its threads park or spin once idle.

### Receivers & Deferred Calls

The receiver chooses where a verb runs and how it completes, and the verb stays the same.
Called on the index, a verb runs on the calling thread; on `index.on(executor)` it blocks on that executor, refused while another call holds it; on `index.deferred(executor)` it submits there and answers a `Deferred` at once.
`DenseIndex`, `DenseIndexOn` and `DenseIndexDeferredOn` take each verb with the same arguments, and a blocking call takes no executor or completion, with a default config deriving every knob.

```swift
let here = try index.search(queries, wanted: 10, arena: arena)                  // the calling thread
let blocking = try index.on(executor).search(queries, wanted: 10, arena: arena) // blocking, on the executor
let call = try index.deferred(executor).search(queries, wanted: 10, arena: arena) // Deferred<Matches>
let matches = try await call.value  // or: try call.wait()
```

A `Deferred` owns its outcome and its outputs, and keeps alive every object whose memory the call reads, until the call is final.
It borrows the index, the executor and the arena as a blocking call does, since releasing any of them waits for the calls naming it, and its waited result is the same view a blocking call answers.
A blocking call lends its inputs in place and frees its outcome, slots and callbacks on return; a deferred one copies only the keys and paths it borrows.
`status` reads `deferred` until then, through the outcome word with acquire ordering, and `wait()` blocks and answers the result or throws the failure, the same every time it is asked.
`value` waits on a Dispatch thread and then reads the result in the caller's isolation, so an `async` caller suspends rather than blocks, and the cooperative pool keeps its threads.
Releasing an unfinished one waits for it first.

```swift
let call = try index.deferred(executor).search(queries, wanted: 10, arena: arena)
if call.status == .deferred {
    // other work
}
let matches = try await call.value  // or: try call.wait()
```

A failure this binding catches before the call crosses throws at submission, and one the library catches arrives through `status` and `wait`.
One call holds an executor at a time, so a second call finding it held finishes at once with `contended`, and nothing queues.
A deferred call on a caller-exclusive pool runs on the pool's thread 0, so polling `status` 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.
Calls depending on each other are ordered by waiting on the first before submitting the second.
Rows built over a `Tensor` stay alive with the call, while memory borrowed through a `MatrixView` or a softmax carry must outlive it.
The constructors that the C interface lets fan out take an `executor` in their config and run on the calling thread without one.

`import USearch`

## Deferred

A call submitted to an executor, which finishes there while the caller does other work.

```swift
final class Deferred<Value>
```

It owns the call's outcome and outputs, and keeps alive every object whose memory the call reads,
until the call is final. The handles it names, the arena among them, it borrows as a blocking
call does. Releasing an unfinished one waits for it first.

Conforms to: `Sendable`

## status

[`deferred`](https://www.unum.cloud/docs/usearch/swift/errors.md#deferred) until the call is final, then [`success`](https://www.unum.cloud/docs/usearch/swift/errors.md#success) or its failure, read without blocking.

```swift
var status: Status { get }
```

Binding-only: reads the status word [`wait`](#wait) would, with its acquire ordering.

## wait

Blocks until the call is final, then answers its result or throws its failure, the same every time it is asked.

```swift
func wait() throws(USearchError) -> Value
```

## value

Waits for the call on a Dispatch thread, so an `async` caller suspends rather than blocks, and the cooperative pool keeps every thread; the result is read back in the caller's isolation.

```swift
nonisolated(nonsending) var value: Value { get async throws(USearchError) }
```

Binding-only: runs [`wait`](#wait).

## Mood

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

```swift
struct Mood
```

Conforms to: `Hashable`, `Sendable`, `CustomStringConvertible`, `Equatable`

## parked

Idle threads and streams sleep; the next call pays a wake-up.

```swift
static let parked: Mood
```

## spinning

Idle threads and streams stay hot, trading power for the next call's latency.

```swift
static let spinning: Mood
```

## description

The mood rendered as the library spells it.

```swift
var description: String { get }
```

## init

Reads a spelling back, and nil for one no mood carries.

```swift
init?(name: String)
```

## Executor

The host threads or device streams a fanned-out verb runs on, and the traversal scratch each of them walks with.

```swift
final class Executor
```

One executor serves any number of index handles, so separate categories of indexes share one
machine's cores or devices instead of each claiming a private set. Its kind is fixed by the
factory that spawned it and must match the residency of every handle it drives; a mismatch
reports [`device`](https://www.unum.cloud/docs/usearch/swift/errors.md#device).

A verb called on the index itself runs on the calling thread - single-threaded on RAM, on the
handle's device and default stream on VRAM. Calls on one executor run in submission order, and
index handles stay freely shareable.

Conforms to: `Sendable`

## residency

Where it computes, which the factory that spawned it named.

```swift
let residency: Residency
```

## forRam

Spawns host threads for RAM-resident indexes, interleaved across the compute domains local to [`memoryDomains`](https://www.unum.cloud/docs/usearch/swift/serialization.md#memoryDomains) - the very list the indexes were initialized with.

```swift
static func forRam(
    memoryDomains: [Int32] = [],
    cpuClass: CPUClass? = nil,
    threads: Int = 0,
    deferredLimit: Int = 0
) throws(USearchError) -> Executor
```

Zero `threads` takes 7/8 of the cores those domains carry, since full occupancy starves the
ordered publication path. Every factory's `deferredLimit` sizes the table of deferred calls
it tracks at once, and zero takes a default. A [`cpuClass`](https://www.unum.cloud/docs/usearch/swift/introspection.md#cpuClass) narrows the threads' waiters and
atomics to that class's; nil derives the CPU's own.

## onPool

Creates a RAM executor over a borrowed ForkUnion `fu_pool_t`, so several libraries in one process share one set of threads while each keeps its own scratch.

```swift
static func onPool(
    memoryDomains: [Int32] = [],
    cpuClass: CPUClass? = nil,
    pool: UnsafeMutableRawPointer,
    deferredLimit: Int = 0
) throws(USearchError) -> Executor
```

The pool must outlive
the executor, and keeps its lender's mood.

## forNvme

Spawns host threads for NVMe-resident indexes, one submission ring apiece, across the compute domains local to the devices [`paths`](https://www.unum.cloud/docs/usearch/swift/serialization.md#paths) names.

```swift
static func forNvme(
    paths: [String] = [],
    cpuClass: CPUClass? = nil,
    threads: Int = 0,
    deferredLimit: Int = 0
) throws(USearchError) -> Executor
```

Zero `threads` derives from those devices' queue capabilities.

## forVram

Opens one submission stream on every named device, all of them driven by the one host thread that calls the verbs - which is why this factory takes no thread count.

```swift
static func forVram(
    devices: [Int32] = [],
    gpuClass: GPUClass? = nil,
    streams: [UnsafeMutableRawPointer?]? = nil,
    scratchLimit: Int = 0,
    deferredLimit: Int = 0
) throws(USearchError) -> Executor
```

`streams` borrows the caller's CUDA streams, one per device in [`devices`](https://www.unum.cloud/docs/usearch/swift/serialization.md#devices) order, and nil
creates the executor's own. A zero `scratchLimit` lets per-device scratch grow as geometry
asks. A [`gpuClass`](https://www.unum.cloud/docs/usearch/swift/introspection.md#gpuClass) the devices do not run is refused with [`unsupported`](https://www.unum.cloud/docs/usearch/swift/errors.md#unsupported).

## drain

Waits for every call submitted to this executor, then adopts `mood` whenever it next goes idle; a failure is the executor's own, such as a lost device, never one of a drained call.

```swift
func drain(mood: Mood = .parked) throws(USearchError)
```

## DenseIndexOn

An index's verbs on an executor, each blocking until final after every call submitted there before it; see `DenseIndex.on(_:)` and the index's own verbs for what each one does.

```swift
struct DenseIndexOn
```

A blocking call borrows the arena it is given, and its result reads it until the arena's next
call.

Conforms to: `Sendable`

## *

Reserves capacity for a total number of entries, the current size included.

```swift
func reserve(_ capacity: Int) throws(USearchError)
```

## *

Erases all entries, keeping the reserved capacity and the frozen geometry.

```swift
func clear() throws(USearchError)
```

## *

Reports the frozen metadata and the current counters in one call.

```swift
func describe() throws(USearchError) -> DenseIndexDescription
```

## *

The number of entries stored under a key; zero means the index holds none.

```swift
func count(key: Key) throws(USearchError) -> Int
```

## contains

Binding-only: calls [`count`](https://www.unum.cloud/docs/usearch/swift/retrieval-and-streaming.md#count).

```swift
func contains(key: Key) throws(USearchError) -> Bool
```

## *

Retrieves every vector stored under a key into `arena`, one row per entry sharing the key.

```swift
func get<Value>(
    key: Key,
    as value: Value.Type,
    arena: Arena
) throws(USearchError) -> DenseVectors<Value> where Value : ScalarValue
```

## *

Inserts rows of vectors under their keys, all or nothing.

```swift
func insert(
    keys: [Key],
    vectors: RowsView,
    config: DenseInsertConfig = DenseInsertConfig()
) throws(USearchError)
```

## *

Re-selects the neighbors of every stored entry against the finished graph, healing islands.

```swift
@discardableResult func refine(
    config: DenseRefineConfig = DenseRefineConfig()
) throws(USearchError) -> DenseRefineReport
```

## *

Audits how much of the graph a search can reach from its landmarks.

```swift
func health() throws(USearchError) -> DenseReachability
```

## *

Resolves rows of queries into up to [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) matches apiece, written in `arena`.

```swift
func search(
    _ queries: RowsView,
    wanted: Int,
    arena: Arena,
    config: DenseSearchConfig = DenseSearchConfig()
) throws(USearchError) -> Matches
```

## *

Scores multi-row queries against multi-vector documents by late interaction, into `arena`.

```swift
func maxsim(
    _ queries: RowsView,
    rowsPerQuery: Int,
    wanted: Int,
    arena: Arena,
    config: DenseMaxsimConfig = DenseMaxsimConfig()
) throws(USearchError) -> DenseProducts
```

## *

The approximate sparse product of rows against the indexed vectors, written in `arena`.

```swift
func multiply(
    _ left: RowsView,
    arena: Arena,
    config: DenseMultiplyConfig = DenseMultiplyConfig()
) throws(USearchError) -> DenseProducts
```

## *

Softmax attention of query heads over every indexed key their walks score, into `arena`.

```swift
func attend<Value>(
    _ queries: RowsView,
    lookup: ValueLookup,
    as value: Value.Type,
    arena: Arena,
    config: DenseAttendConfig = DenseAttendConfig()
) throws(USearchError) -> DenseVectors<Value> where Value : ScalarValue
```

## *

Absorbs every donor into this index, keeping their graphs and consuming the donors.

```swift
@discardableResult func absorb(
    _ donors: [DenseIndex],
    config: DenseAbsorbConfig = DenseAbsorbConfig()
) throws(USearchError) -> DenseRefineReport
```

## *

Splits this index into empty `receivers`, graph-local parts keeping their edges.

```swift
@discardableResult func split(
    into receivers: [DenseIndex],
    config: DenseSplitConfig = DenseSplitConfig()
) throws(USearchError) -> DenseRefineReport
```

## *

Draws up to [`wanted`](https://www.unum.cloud/docs/usearch/swift/linear-algebra.md#wanted) keys around [`config.focus`](https://www.unum.cloud/docs/usearch/swift/retrieval-and-streaming.md#focus), or across the whole index, into `arena`.

```swift
func sample(
    wanted: Int,
    arena: Arena,
    config: DenseSampleConfig = DenseSampleConfig()
) throws(USearchError) -> DenseDraws
```

## *

Writes the index under a path, in the layout its extension picks.

```swift
func save(path: String, config: DenseSaveConfig = DenseSaveConfig()) throws(USearchError)
```

## save*

Writes the index into `arena` as one monolith, the bytes a `.safegraphs` path holds.

```swift
func saveBuffer(
    arena: Arena,
    config: DenseSaveBufferConfig = DenseSaveBufferConfig()
) throws(USearchError) -> Monolith
```

## cursor

Opens a cursor whose every pull blocks on this executor.

```swift
func cursor(starts: [Key] = []) throws(USearchError) -> DenseCursor
```

## searchStream

Opens a stream whose every pull blocks on this executor.

```swift
func searchStream(
    _ query: RowsView,
    config: DenseSearchStreamInitConfig = DenseSearchStreamInitConfig()
) throws(USearchError) -> DenseSearchStream
```

## DenseIndexDeferredOn

An index's verbs submitted to an executor, each answering a [`Deferred`](#Deferred) at once; see `DenseIndex.deferred(_:)` and the index's own verbs for what each one does.

```swift
struct DenseIndexDeferredOn
```

A failure this binding catches before the call crosses throws at submission. Every object whose
memory a call reads, like rows built over a `Tensor`, stays alive until it is final, and memory
borrowed from elsewhere must outlive it too. The index, the executor and the arena are borrowed
as a blocking call borrows them, since releasing any of them waits for the calls naming it.

Conforms to: `Sendable`