Mojo · Platform Notes

Platform Notes

3.0.0-rc.1 · 4c3e5023

§ What This Binding Does Not Expose

  • Progress on loads, saves, absorbs and splits. Their entry points take no config, so those calls run without a handler.
  • Deferred cursors and streams. DenseIndexDeferredOn offers neither, since their pulls block.

§ Design

  • A thin layer over the C ABI. Every name follows c/usearch/: a C verb usearch_dense_<verb> is a <verb> here, and enums mirror C enums, never strings.
  • Pointers keep their types and their borrows. A C pointer that may be null is an Optional[Pointer], a view carries the origin of what it borrows into its pointer, and only opaque handles and void * state cross as an integer Address.
  • The receiver chooses, the verb stays. The index runs a verb on the calling thread, on(executor) blocks on an executor, and deferred(executor) submits it, all with the same arguments.
  • Deferred calls use the language’s own idioms. status polls through usearch_outcome_status, wait blocks through usearch_outcome_wait, and the origins a Deferred carries keep everything it borrows alive until it is gone.
  • No life of its own. The binding starts no threads and keeps no queues; releasing a Deferred rides Mojo’s destruction at last use, which waits for the call first.
  • Arenas are lent and reused, never shared. Every output whose length scales with the call lands in an arena the caller passes; the binding stamps each arena with a counter that every view checks before reading, and keeps no call counts.
  • Nothing costs anything until it is used. Submitting a call allocates nothing, and an arena allocates only when a call writes into it.
  • Blocking calls live on the stack. A blocking call keeps its outcome and outputs in stack slots and allocates nothing of its own; a deferred one moves those slots to one heap allocation it frees once final.
  • ScalarKind, not Scalar. Types drop usearch_ and _t from their C names, except ScalarKind, which keeps clear of Mojo’s built-in Scalar.