Executors

A call that names no executor runs on the calling thread, single-threaded on RAM and on the handle’s device and default stream on VRAM, and spawns nothing behind the caller’s back. An Executor owns the workers instead, and one can be shared by several indexes. Each residency has its own factory:

const hostPool = usearch.Executor.forRam({ threads: 2, memoryDomains: [0, 1] });
const devicePool = usearch.Executor.forVram({ devices: [0, 1], scratchLimit: 1 << 30 });
const diskPool = usearch.Executor.forNvme({ threads: 4, paths: ['/mnt/nvme0', '/mnt/nvme1'] });

forRam creates an executor of host threads and spreads them over the named NUMA nodes, absent naming none and spreading them over every node. onPool borrows an existing ForkUnion pool by its BigInt address instead of spawning one. forVram opens one CUDA stream per named ordinal, absent taking one free device, or borrows the streams given as BigInt addresses, one per device. It takes no thread count because one host thread drives one stream per device, so the device list is what sizes the work rather than a number of workers. forNvme opens one submission ring per worker over the named device or directory paths, absent deriving them. Each factory’s config holds only what its own C structure takes: memoryDomains for RAM, devices for VRAM, and paths for NVMe.

drain(mood) waits until no call holds the executor, then idles the workers in a usearch.Mood: Parked threads sleep, and Spinning ones stay hot for the next call’s latency. The collector frees an executor eventually, and free() waits out the call holding it and joins its workers now; a freed executor is refused by every later call.

§ 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 usearch.Deferred:

const matches = index.search(queries, 10, arena);                 // the calling thread
const onPool = index.on(executor).search(queries, 10, arena);     // blocking, holding the executor until it returns
const call = index.deferred(executor).search(queries, 10, arena); // Deferred<Matches>

DenseIndexOn and DenseIndexDeferredOn offer the same verbs with the same arguments. Only the blocking receivers add contains, cursor and searchStream, whose every pull blocks, and only the index itself adds attend. Constructors address no index yet, so no receiver offers them; the ones the C interface lets fan out take an executor in their config.

A Deferred keeps everything the library reads or writes alive until its call is final: the outcome, the inputs, the outputs and every handle it names. It is awaitable, implementing the thenable protocol, so await reaches it like any other asynchronous value:

const call = index.deferred(executor).search(queries, 10, arena);
if (call.status === usearch.Status.Deferred) {
  // other work
}
const matches = await call; // or: call.wait()

await waits on the libuv pool, so the event loop keeps turning, while wait() blocks the calling thread. Both answer the same cached result, or throw the same failure, however often they are asked, and status reads the outcome without blocking. using call = ... waits for the call before its block ends, and one dropped unfinished is handed back to the collector until it is final, so nothing it borrowed is freed under the library. Refusals this binding catches before the call crosses, like keys that do not match the rows, throw at submission.

One call holds an executor at a time, so a second call finding it 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 status alone finishes it, and its progress handler and predicate run on the pool’s threads; a single thread, WebAssembly or a VRAM executor runs it at submission. Calls depending on each other are ordered by waiting on the first before submitting the second. The arrays a deferred verb is handed must not change until it is final, since the library reads them until then.