Mojo · Residency

Residency

from usearch import Residency, RamOptions, VramOptions, … 3.0.0-rc.1 · 4c3e5023

Where the payload lives is the constructor’s name, as in the C lifecycle verbs, so a residency an index lacks has no constructor to call. Each takes only the placement its own hardware has, one shard per entry, and leaving it out derives one.

var domains = [Int32(0), Int32(1)]
var in_ram = DenseIndex.init_ram(library, options, RamOptions.on(domains))  # one graph per socket
var devices = [Int32(0), Int32(1), Int32(2), Int32(3)]
var in_vram = DenseIndex.init_vram(library, options, VramOptions.on(devices))  # sharded, never replicated
var on_nvme = DenseIndex.view_nvme(Executor.for_nvme(library), "index.safegraphs")

An NVMe index is only ever viewed: external-memory graphs are never modified in place. Until NVMe checkpoints carry keys, view_nvme answers Status.UNSUPPORTED.

API

StructResidencyWhere an index's payload lives and which engine traverses it - usearch_residency_t. 
struct Residency

Each lifecycle verb names its residency, as DenseIndex.init_vram does, so this tag only travels through the name tables: Library.residency_name and Library.residency_from_name.

Fields

codec_intThe raw usearch_residency_t value the ABI exchanges.

Values

RAMResidency(Int32(1))Volatile memory traversed by CPU threads - the concurrent baseline.
VRAMResidency(Int32(2))Accelerator memory traversed by GPU warps on the chosen devices.
NVMEResidency(Int32(3))Persisted storage traversed through pluggable I/O engines, sized past RAM.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable
StructRamOptionsThe host memory domains a RAM-resident index places its shards in - usearch_ram_options_t.3 
struct RamOptions[origin: ImmOrigin = ImmUntrackedOrigin]

One shard per named NUMA node, so a dual-socket box names two and gets two graphs whose traversals stay local to the cores that walk them. The engine's payload blocks always claim huge pages, falling back to base pages where none are provisioned.

Parameters

originImmOrigincomptimeThe borrowed node-id array, named so it outlives the constructor that reads it.

Fields

memory_domainsAddressThe int32_t node ids to place shards on; NULL_ADDRESS derives every node the process may use.
memory_domains_countc_size_tHow many ids the array holds; zero derives.
shard_capacityc_size_tEntries one shard holds before the index opens another shard generation; zero derives.
cpu_classCpuClassThe class to dispatch as; UNKNOWN derives the CPU's own.
memory_limitc_size_tBytes an NVMe view's key tables may take on each named domain; zero sets no ceiling.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable
__init__Derives every memory domain the process may allocate on. 
def __init__(out self)
onNames the NUMA nodes explicitly, borrowing the caller's array for the call. 
def on[domains_origin: ImmOrigin, //](
    memory_domains: Span[Int32, domains_origin]
) -> RamOptions[domains_origin]

Parameters

domains_originImmOrigincomptimeThe run's origin, inferred from the argument.
memory_domainsSpan[Int32, domains_origin]The node ids to place one shard on apiece.

Returns

Options naming exactly those nodes, one shard apiece.
*× 3The same options with the borrow erased - the one instantiation the ABI signature names. 
def untracked(self) -> RamOptions

Returns

Options naming the same array, whose type no longer keeps it alive.
StructVramOptionsThe devices a VRAM-resident index places its shards in - usearch_vram_options_t.2 
struct VramOptions[origin: ImmOrigin = ImmUntrackedOrigin]

Sharded and never replicated, so eight devices host eight slices of one graph rather than eight copies of it. Planes are device-resident: an index outgrowing the named devices fails rather than paging to the host, and the answer is to name more devices.

Parameters

originImmOrigincomptimeThe borrowed ordinal array, named so it outlives the constructor that reads it.

Fields

devicesAddressThe CUDA ordinals to place shards on; NULL_ADDRESS derives one free device.
devices_countc_size_tHow many ordinals the array holds; zero derives.
shard_capacityc_size_tEntries one shard holds before the index opens another shard generation; zero derives.
gpu_classGpuClassThe class to dispatch as; UNKNOWN derives the devices' own.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable
__init__Derives one free device. 
def __init__(out self)
onNames the device ordinals explicitly, borrowing the caller's array for the call. 
def on[devices_origin: ImmOrigin, //](
    devices: Span[Int32, devices_origin]
) -> VramOptions[devices_origin]

Parameters

devices_originImmOrigincomptimeThe run's origin, inferred from the argument.
devicesSpan[Int32, devices_origin]The CUDA ordinals to place one shard on apiece.

Returns

Options naming exactly those devices, one shard apiece.
StructNvmeOptionsThe devices an NVMe-resident index places its shards on - usearch_nvme_options_t.2 
struct NvmeOptions[origin: ImmOrigin = ImmUntrackedOrigin]

A path is whatever identifies a device to the engine that can reach it, so the string is the extension point rather than a field per transport: a filesystem path names a kernel device, a transport identifier names a namespace the kernel no longer owns, and a FUSE mount is a path too. Naming nothing opens every shard where its manifest already points and moves no bytes.

Parameters

originImmOrigincomptimeThe borrowed path array, named so it outlives the constructor that reads it.

Fields

pathsAddressA usearch_bytes_view_t array; NULL_ADDRESS leaves every shard where its manifest points.
paths_countc_size_tHow many paths the array holds; zero derives.
cpu_classCpuClassThe class to dispatch as; UNKNOWN derives the CPU's own.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable
__init__Leaves every shard where its own manifest points. 
def __init__(out self)
onNames the devices or directories explicitly, borrowing the caller's array for the call. 
def on[paths_origin: ImmOrigin, //](
    paths: Span[BytesView, paths_origin]
) -> NvmeOptions[paths_origin]

Parameters

paths_originImmOrigincomptimeThe run's origin, inferred from the argument.
pathsSpan[BytesView, paths_origin]The device or directory names, one shard apiece.

Returns

Options naming exactly those paths, one shard apiece.