# Platform Notes

> UStore for Mojo

### What This Binding Does Not Expose

The five Arrow exports of `c/ustore/arrow.h` stay unbound, as Mojo has no Arrow arrays to hand them.
The accessor layout of a strings batch, which reads strings through a C callback, is not exposed: Mojo passes the two tape layouts.

### Design

Blocking stays simple: a verb on a database or on `db.on(executor)` reads as it would if asynchrony did not exist.
Deferred calls are symmetric, the same verbs on another receiver, observed only through the outcome's status word, and release rides Mojo's own destructor.
Nothing costs anything until used: the binding starts no threads, keeps no counts and caches nothing, so a call is one argument structure built on the stack and one indirect call.

`from ustore import Library, PageEncoding, PagesInsertConfig, …`

## Library

A reference to the loaded engine, cheap to copy and shared by everything it creates.

```mojo
struct Library
```

Every handle carries one, which is what keeps the shared object mapped for as long as anything
can still call into it.

- `shared` `ArcPointer[_Loaded]`: The handle and its symbols, refcounted so the last holder unmaps the object.

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

## __init__

Opens the shared object and resolves it, which every handle then shares.

```mojo
def __init__(out self)
```

Raises: With [`LIBRARY_MISSING`](https://www.unum.cloud/docs/ustore/mojo/errors.md#LIBRARY_MISSING), when nothing is on the loader path, with [`VERSION_MISMATCH`](https://www.unum.cloud/docs/ustore/mojo/errors.md#VERSION_MISMATCH) when what loaded is another major version, or with [`SYMBOL_MISSING`](https://www.unum.cloud/docs/ustore/mojo/errors.md#SYMBOL_MISSING) when it does not export an entry point the binding needs.

## symbols

The resolved entry points, borrowed rather than copied on every call.

```mojo
def symbols(self) -> ref[self.shared.symbols] Symbols
```

## version

The loaded engine's major, minor and patch. Calls `ustore_version`.

```mojo
def version(self) -> Tuple[Int, Int, Int]
```

## version_name

The loaded engine's own version, like "1.0.0". Calls `ustore_version_name`.

```mojo
def version_name(self) -> String
```

## gpu_devices

Fills `devices` with every GPU this process can drive, in the ordinal order a VRAM executor names them by. Calls `ustore_gpu_devices`.

```mojo
def gpu_devices[devices_origin: MutOrigin, //](
    self,
    devices: Span[GPUDevice, devices_origin]
) -> Int
```

- `devices`: Where the listing lands, as many entries as fit; may be empty to only count.

## status_name

The engine's spelling of a status, "unrecognized" for a code it does not name. Calls `ustore_status_name`.

```mojo
def status_name(self, status: Status) -> String
```

## status_from_name

Reads a spelling back; [`INVALID_ARGUMENT`](https://www.unum.cloud/docs/ustore/mojo/errors.md#INVALID_ARGUMENT) when unrecognized. Calls `ustore_status_from_name`.

```mojo
def status_from_name(self, name: StringSpan) -> Status
```

## pattern_kind_name

The engine's spelling of a pattern kind. Calls `ustore_pattern_kind_name`.

```mojo
def pattern_kind_name(self, kind: PatternKind) -> String
```

## pattern_kind_from_name

Reads a spelling back; [`REGEX`](https://www.unum.cloud/docs/ustore/mojo/scans.md#REGEX) when unrecognized. Calls `ustore_pattern_kind_from_name`.

```mojo
def pattern_kind_from_name(self, name: StringSpan) -> PatternKind
```

## case_sensitivity_name

The engine's spelling of a case sensitivity. Calls `ustore_case_sensitivity_name`.

```mojo
def case_sensitivity_name(self, sensitivity: CaseSensitivity) -> String
```

## case_sensitivity_from_name

Reads a spelling back; [`CASED`](https://www.unum.cloud/docs/ustore/mojo/scans.md#CASED) when unrecognized. Calls `ustore_case_sensitivity_from_name`.

```mojo
def case_sensitivity_from_name(self, name: StringSpan) -> CaseSensitivity
```

## mood_name

The engine's spelling of a mood. Calls `ustore_mood_name`.

```mojo
def mood_name(self, mood: Mood) -> String
```

## mood_from_name

Reads a spelling back; [`PARKED`](https://www.unum.cloud/docs/ustore/mojo/batches-and-arenas.md#PARKED) when unrecognized. Calls `ustore_mood_from_name`.

```mojo
def mood_from_name(self, name: StringSpan) -> Mood
```

## cpu_class_name

The engine's spelling of a CPU class, "automatic" for [`UNKNOWN`](https://www.unum.cloud/docs/ustore/mojo/graphs.md#UNKNOWN). Calls `ustore_cpu_class_name`.

```mojo
def cpu_class_name(self, cpu_class: CPUClass) -> String
```

## cpu_class_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/ustore/mojo/graphs.md#UNKNOWN) when unrecognized. Calls `ustore_cpu_class_from_name`.

```mojo
def cpu_class_from_name(self, name: StringSpan) -> CPUClass
```

## transport_name

The engine's spelling of a transport. Calls `ustore_transport_name`.

```mojo
def transport_name(self, transport: Transport) -> String
```

## transport_from_name

Reads a spelling back; [`AUTOMATIC`](https://www.unum.cloud/docs/ustore/mojo/batches-and-arenas.md#AUTOMATIC) when unrecognized. Calls `ustore_transport_from_name`.

```mojo
def transport_from_name(self, name: StringSpan) -> Transport
```

## gds_name

The engine's spelling of a GPUDirect Storage mode. Calls `ustore_gds_name`.

```mojo
def gds_name(self, gds: Gds) -> String
```

## gds_from_name

Reads a spelling back; [`AUTOMATIC`](https://www.unum.cloud/docs/ustore/mojo/batches-and-arenas.md#AUTOMATIC) when unrecognized. Calls `ustore_gds_from_name`.

```mojo
def gds_from_name(self, name: StringSpan) -> Gds
```

## gpu_vendor_name

The engine's spelling of a GPU vendor. Calls `ustore_gpu_vendor_name`.

```mojo
def gpu_vendor_name(self, vendor: GPUVendor) -> String
```

## gpu_vendor_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/ustore/mojo/graphs.md#UNKNOWN) when unrecognized. Calls `ustore_gpu_vendor_from_name`.

```mojo
def gpu_vendor_from_name(self, name: StringSpan) -> GPUVendor
```

## gpu_class_name

The engine's spelling of a GPU class. Calls `ustore_gpu_class_name`.

```mojo
def gpu_class_name(self, gpu_class: GPUClass) -> String
```

## gpu_class_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/ustore/mojo/graphs.md#UNKNOWN) when unrecognized. Calls `ustore_gpu_class_from_name`.

```mojo
def gpu_class_from_name(self, name: StringSpan) -> GPUClass
```

## predicate_cost_name

The engine's spelling of a predicate cost. Calls `ustore_predicate_cost_name`.

```mojo
def predicate_cost_name(self, cost: PredicateCost) -> String
```

## predicate_cost_from_name

Reads a spelling back; [`CHEAP`](https://www.unum.cloud/docs/ustore/mojo/scans.md#CHEAP) when unrecognized. Calls `ustore_predicate_cost_from_name`.

```mojo
def predicate_cost_from_name(self, name: StringSpan) -> PredicateCost
```

## durability_name

The engine's spelling of a durability. Calls `ustore_durability_name`.

```mojo
def durability_name(self, durability: Durability) -> String
```

## durability_from_name

Reads a spelling back; [`BUFFERED`](https://www.unum.cloud/docs/ustore/mojo/reads-and-writes.md#BUFFERED) when unrecognized. Calls `ustore_durability_from_name`.

```mojo
def durability_from_name(self, name: StringSpan) -> Durability
```

## watch_name

The engine's spelling of a watch. Calls `ustore_watch_name`.

```mojo
def watch_name(self, watch: Watch) -> String
```

## watch_from_name

Reads a spelling back; [`KEYS`](https://www.unum.cloud/docs/ustore/mojo/transactions.md#KEYS) when unrecognized. Calls `ustore_watch_from_name`.

```mojo
def watch_from_name(self, name: StringSpan) -> Watch
```

## scan_mode_name

The engine's spelling of a scan mode. Calls `ustore_scan_mode_name`.

```mojo
def scan_mode_name(self, mode: ScanMode) -> String
```

## scan_mode_from_name

Reads a spelling back; [`ORDERED`](https://www.unum.cloud/docs/ustore/mojo/scans.md#ORDERED) when unrecognized. Calls `ustore_scan_mode_from_name`.

```mojo
def scan_mode_from_name(self, name: StringSpan) -> ScanMode
```

## scan_direction_name

The engine's spelling of a scan direction. Calls `ustore_scan_direction_name`.

```mojo
def scan_direction_name(self, direction: ScanDirection) -> String
```

## scan_direction_from_name

Reads a spelling back; [`ASCENDING`](https://www.unum.cloud/docs/ustore/mojo/scans.md#ASCENDING) when unrecognized. Calls `ustore_scan_direction_from_name`.

```mojo
def scan_direction_from_name(self, name: StringSpan) -> ScanDirection
```

## drop_mode_name

The engine's spelling of a drop mode. Calls `ustore_drop_mode_name`.

```mojo
def drop_mode_name(self, mode: DropMode) -> String
```

## drop_mode_from_name

Reads a spelling back; [`COLLECTION`](https://www.unum.cloud/docs/ustore/mojo/collections.md#COLLECTION) when unrecognized. Calls `ustore_drop_mode_from_name`.

```mojo
def drop_mode_from_name(self, name: StringSpan) -> DropMode
```

## isolation_name

The engine's spelling of an isolation. Calls `ustore_isolation_name`.

```mojo
def isolation_name(self, isolation: Isolation) -> String
```

## isolation_from_name

Reads a spelling back; [`STRICT_SERIALIZABLE`](https://www.unum.cloud/docs/ustore/mojo/transactions.md#STRICT_SERIALIZABLE) when unrecognized. Calls `ustore_isolation_from_name`.

```mojo
def isolation_from_name(self, name: StringSpan) -> Isolation
```

## engine_name

The engine's spelling of an engine. Calls `ustore_engine_name`.

```mojo
def engine_name(self, engine: Engine) -> String
```

## engine_from_name

Reads a spelling back; [`RAM`](https://www.unum.cloud/docs/ustore/mojo/batches-and-arenas.md#RAM) when unrecognized. Calls `ustore_engine_from_name`.

```mojo
def engine_from_name(self, name: StringSpan) -> Engine
```

## modality_name

The engine's spelling of a modality. Calls `ustore_modality_name`.

```mojo
def modality_name(self, modality: Modality) -> String
```

## modality_from_name

Reads a spelling back; [`NONE`](https://www.unum.cloud/docs/ustore/mojo/transactions.md#NONE) when unrecognized. Calls `ustore_modality_from_name`.

```mojo
def modality_from_name(self, name: StringSpan) -> Modality
```

## change_kind_name

The engine's spelling of a change kind. Calls `ustore_change_kind_name`.

```mojo
def change_kind_name(self, kind: ChangeKind) -> String
```

## change_kind_from_name

Reads a spelling back; [`WRITE`](https://www.unum.cloud/docs/ustore/mojo/scans.md#WRITE) when unrecognized. Calls `ustore_change_kind_from_name`.

```mojo
def change_kind_from_name(self, name: StringSpan) -> ChangeKind
```

## ingest_order_name

The engine's spelling of an ingest order. Calls `ustore_ingest_order_name`.

```mojo
def ingest_order_name(self, order: IngestOrder) -> String
```

## ingest_order_from_name

Reads a spelling back; [`SORTED`](https://www.unum.cloud/docs/ustore/mojo/reads-and-writes.md#SORTED) when unrecognized. Calls `ustore_ingest_order_from_name`.

```mojo
def ingest_order_from_name(self, name: StringSpan) -> IngestOrder
```

## docs_field_type_name

The engine's spelling of a field type, as [`F64`](https://www.unum.cloud/docs/ustore/mojo/documents.md#F64) spells "f64". Calls `ustore_docs_field_type_name`.

```mojo
def docs_field_type_name(self, field_type: FieldType) -> String
```

## docs_field_type_from_name

Reads a spelling back; [`JSON`](#JSON) when unrecognized. Calls `ustore_docs_field_type_from_name`.

```mojo
def docs_field_type_from_name(self, name: StringSpan) -> FieldType
```

## docs_modification_name

The engine's spelling of a modification. Calls `ustore_docs_modification_name`.

```mojo
def docs_modification_name(self, modification: Modification) -> String
```

## docs_modification_from_name

Reads a spelling back; [`UPSERT`](https://www.unum.cloud/docs/ustore/mojo/documents.md#UPSERT) when unrecognized. Calls `ustore_docs_modification_from_name`.

```mojo
def docs_modification_from_name(self, name: StringSpan) -> Modification
```

## vertex_role_name

The engine's spelling of a vertex role. Calls `ustore_vertex_role_name`.

```mojo
def vertex_role_name(self, role: VertexRole) -> String
```

## vertex_role_from_name

Reads a spelling back; [`UNKNOWN`](https://www.unum.cloud/docs/ustore/mojo/graphs.md#UNKNOWN) when unrecognized. Calls `ustore_vertex_role_from_name`.

```mojo
def vertex_role_from_name(self, name: StringSpan) -> VertexRole
```

## page_encoding_name

The engine's spelling of a page encoding. Calls `ustore_page_encoding_name`.

```mojo
def page_encoding_name(self, encoding: PageEncoding) -> String
```

## page_encoding_from_name

Reads a spelling back; [`HTML`](#HTML) when unrecognized. Calls `ustore_page_encoding_from_name`.

```mojo
def page_encoding_from_name(self, name: StringSpan) -> PageEncoding
```

## PageEncoding

The encoding a page or a fragment is imported from or rendered into, `ustore_page_encoding_t`.

```mojo
struct PageEncoding
```

- `HTML` = `PageEncoding(Int32(0))`: HTML, not yet imported or rendered, answering [`UNSUPPORTED`](https://www.unum.cloud/docs/ustore/mojo/errors.md#UNSUPPORTED).
- `XML` = `PageEncoding(Int32(1))`: XML, with every element and attribute kept as written.
- `MARKDOWN` = `PageEncoding(Int32(2))`: Markdown, not yet imported or rendered, answering [`UNSUPPORTED`](https://www.unum.cloud/docs/ustore/mojo/errors.md#UNSUPPORTED).
- `TEXT` = `PageEncoding(Int32(3))`: The text of every run in document order, with structure dropped.
- `JSON` = `PageEncoding(Int32(4))`: The element tree as JSON, not yet imported or rendered, answering [`UNSUPPORTED`](https://www.unum.cloud/docs/ustore/mojo/errors.md#UNSUPPORTED).
- `code` `c_int`: The raw `ustore_page_encoding_t` value the ABI exchanges.

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

## PagesInsertConfig

Where inserted fragments land, the keys they take, and how they read.

```mojo
struct PagesInsertConfig[elements_origin: ImmOrigin = ImmUntrackedOrigin, parents_origin: ImmOrigin = ImmUntrackedOrigin, anchors_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `elements_origin` (comptime): The borrowed element keys.
- `parents_origin` (comptime): The borrowed parents.
- `anchors_origin` (comptime): The borrowed anchors.

- `elements` `StridedView[Key, elements_origin]`: Keys to give the inserted elements; nil or zeroed mints one.
- `parents` `StridedView[Key, parents_origin]`: Parents the elements land under; nil stands for the root.
- `anchors` `StridedView[Key, anchors_origin]`: Siblings after which the elements land; nil stands for the front.
- `encoding` `PageEncoding`: Encoding of the fragments.
- `durability` `Durability`: How durable the edits are once the call finishes at the head.

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

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    elements: StridedView[Key, elements_origin] = StridedView(),
    parents: StridedView[Key, parents_origin] = StridedView(),
    anchors: StridedView[Key, anchors_origin] = StridedView(),
    encoding: PageEncoding = PageEncoding.XML,
    durability: Durability = Durability.BUFFERED
)
```

## PagesReadConfig

Which subtrees a read renders, and into what.

```mojo
struct PagesReadConfig[elements_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `elements_origin` (comptime): The borrowed element keys.

- `elements` `StridedView[Key, elements_origin]`: Elements to render with their subtrees; zeroed or nil renders whole pages.
- `outputs_encoding` `PageEncoding`: Encoding the renderings are converted into.
- `values` `Bool`: Whether the renderings come too, or only presences and lengths.

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

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    elements: StridedView[Key, elements_origin] = StridedView(),
    outputs_encoding: PageEncoding = PageEncoding.XML,
    values: Bool = True
)
```

## PagesScanConfig

The bounds, order and filter of a scan over page keys.

```mojo
struct PagesScanConfig[end_origin: ImmOrigin = ImmUntrackedOrigin, filter_origin: ImmOrigin = ImmUntrackedOrigin]
```

- `end_origin` (comptime): The borrowed end keys.
- `filter_origin` (comptime): The borrowed filter.

- `end_keys` `StridedView[Key, end_origin]`: Key every scan stops before, exclusive; zeroed bounds nothing.
- `direction` `ScanDirection`: Ascending or descending from the start keys.
- `mode` `ScanMode`: In what order the page keys come.
- `filter` `BytesView[filter_origin]`: A path in StringZilla's XPath subset every listed page holds a node of; zeroed lists every page.
- `predicate` `Predicate`: The caller's verdict on the listed keys.
- `progress` `Progress`: Reports the scans finished, and stops the call where it says to.

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

## __init__

Names only the knobs that differ from the defaults.

```mojo
def __init__(
    out self,
    *,
    end_keys: StridedView[Key, end_origin] = StridedView(),
    direction: ScanDirection = ScanDirection.ASCENDING,
    mode: ScanMode = ScanMode.ORDERED,
    filter: BytesView[filter_origin] = BytesView(),
    predicate: Predicate = Predicate(),
    progress: Progress = Progress()
)
```