Batches and Arenas

§ Receivers & Deferred Calls

The receiver chooses where a verb runs, what it sees and how it completes, and the verb stays the same. A database, transaction or snapshot runs a verb on the calling thread, handle.on(executor) blocks on an executor, and handle.deferred(executor) submits it there and answers a Deferred:

db.write(collections, keys, values)                       # the head, on the calling thread
db.on(executor).write(collections, keys, values)          # blocking, on the executor
var call = db.deferred(executor).read(collections, keys, arena)  # Deferred[...]
print(call.wait().present(0))

On and DeferredOn offer the same verbs with the same arguments, and the blocking verbs are written once, in the BlobsVerbs, StringsVerbs, DocsVerbs, GraphVerbs, PagesVerbs and DatabaseVerbs traits every blocking receiver conforms to. The verb names follow the C ones: blobs verbs are unprefixed, as write and scan, and the other modalities carry theirs, as strings_scan, docs_gather, graph_read_edges and pages_insert. Reads see the head of a database, a transaction, or a snapshot; writes join the receiver’s transaction, recording their keys unless it came from txn.unwatched(), and a snapshot’s receiver, which has none, writes at the head. stage, commit, rollback and reset act on the receiver’s transaction and save on its snapshot, and the engine answers Status.UNINITIALIZED for a receiver without one.

A Deferred owns its outcome and outputs until the call is final, and borrows the arena and every input it was handed, which Mojo keeps alive for as long as the Deferred is; freeing the database, the executor or a transaction waits for the calls naming them. Mojo has no runtime of its own to await on, so wait is the whole interface: it blocks in ustore_outcome_wait until the call is final, then answers the result or raises the failure, as many times as it is asked. status reads the outcome without blocking, and destroying an unfinished Deferred waits for it.

§ Arenas

Every output whose length only the call knows, values, keys, offsets, bounds, columns and edges, lands in an Arena you pass, and the verb answers a view over it without copying. Arena(executor) places it where that executor computes, decided once, and Arena(library) makes host pages for the calling thread. Each call rewinds its arena, so the previous call’s views die and a steady loop allocates once; reading a stale one raises Status.INVALID_ARGUMENT. To keep a result past the next call, pass that call another arena, and give every deferred call its own.

§ Progress & Cancellation

Scans take their start keys and how many keys every scan keeps, plus an optional config for the end keys, the direction, the patterns or filter, the predicate and the progress handler:

def stop_at_once(finished: Int, total: Int, seen: Pointer[Int, MutAnyOrigin]) -> Continuation:
    seen[] = finished
    return Continuation.CANCEL

def admit_even(keys: Span[Key, MutAnyOrigin], admissions: Span[Admission, MutAnyOrigin], state: Pointer[Int, MutAnyOrigin]):
    for index in range(len(keys)):
        admissions[index] = Admission.ADMIT if keys[index].uuid.bytes[15] % 2 == 0 else Admission.REJECT

var seen = 0
var config = BlobsScanConfig(predicate=Predicate.of[admit_even](Pointer(to=seen)))
var runs = db.scan(CollectionsView.repeating(people), KeysView.repeating(start), 100, arena, config)
_ = db.scan(collections, starts, 100, arena, BlobsScanConfig(progress=Progress.of[stop_at_once](Pointer(to=seen))))  # raises Status.CANCELLED

Handlers are compile-time parameters, since a capturing closure cannot cross into C, and their state crosses beside them as a pointer that must outlive the call. Progress handlers return a value, which Mojo 1.2 is confirmed to pass back on Linux x86-64; Linux AArch64 and macOS rest on the CI matrix.