Platform Notes

§ What This Crate Does Not Expose

These C entry points also take a deferred completion, but the crate calls them blocking, whatever receiver you hold:

• ustore_database_init_ram, ustore_database_view_rocksdb and the ustore_database_open_* family, whose options name the executor the open runs on.
• ustore_database_describe and ustore_collection_create.
• ustore_transaction_init for a new transaction, and ustore_snapshot_init.
• ustore_blobs_cursor_next, which runs on the executor of the view that opened the cursor, and opens only from a blocking one.

Every call through a Collection, and Executor::drain, block as well.

The crate binds none of these:

• The strings cursor, which export_arrow drives, and the range removals of ustore_pages_remove.
• The progress of a cursor pull, which reports a single unit once its page is out.
• The lengths a read writes beside its values, which the tape’s offsets already carry.

§ Design

The crate is a thin layer over the C ABI in c/ustore/, and every rule below follows from that.

• Verbs are named as in C. A C verb drops only what its receiver already names, so ustore_docs_write is docs_write on a view and ustore_collection_find is collection_find, while the blob verbs, which reach documents as well, keep their bare names. The constructors keep C’s lifecycle names: init_ram starts empty, open_<engine> serves a directory in place, and view_rocksdb serves one read-only.
• Blocking verbs return Result directly. database.head().read(people, &[ada, grace], &mut arena)? takes no executor, completion or call value, and nothing about asynchrony reaches a caller who never asks for it.
• On<'view, Parent, Completion> makes the receiver a type, not a flag. What every C argument struct puts before its inputs, the view, the executor and the completion, is chosen by the receiver a verb is called on: database.head(), transaction.view(watch) or snapshot.view(), then .on(&executor) or .deferred(&executor), where transaction.on(&executor) and transaction.deferred(&executor) watch the keys. Each verb is written once, generic over the completion, so a DeferredOn offers the same verbs with the same arguments and answers a Deferred instead of the result. Opening a database has no view yet, so its options name the executor, and the open blocks.
• A call the view cannot serve does not compile. The parent, a Database, a Transaction or a Snapshot, decides the verbs beyond the reads: only a transaction stages, commits, rolls back and resets, only the head clears, compacts and drops collections, only a snapshot saves, and nothing writes through a snapshot.
• Ragged inputs cross as they lie. A slice of entries lends its keys as a strided run and its values through an accessor over the same records, and owned values cross as a tape of 32-bit or 64-bit offsets, so nothing is staged on the way in.
• Arenas are lent and reused, never shared or hidden. Executors make them through ustore_arena_init, and every verb whose outputs scale with the call borrows one as &mut Arena, blocking or deferred, while its result borrows it in turn, so the borrow checker retires stale views at compile time. No handle keeps an arena of its own.
• Shorthand makes one-off arenas. A Collection call with no arena to pass, such as get or contains, makes an arena for that call, copies its result out, and frees it: slower than reuse, and stateless.
• A DeferredOn refuses borrowed inputs at compile time. The library reads a deferred call’s inputs after the verb returns, so the Accepts bound admits only owned ones, and passing &[Key] fails with “a deferred view needs owned inputs”. The arena stays a borrow, which is safe because ustore_arena_free waits for the calls writing into it.
• Deferred calls use the language’s own idioms. status polls through ustore_outcome_status, wait blocks through ustore_outcome_wait, and a Deferred is IntoFuture, so .await polls the status, asking to be polled again while the call is not final, since the library has no wake-up.
• No life of its own. The crate starts no threads and keeps no counts or queues, and needs no async runtime; releasing a Deferred rides Drop, which waits for the call first.
• Nothing costs anything until it is used. A blocking call allocates no box, a deferred one allocates one, and an arena allocates only when a call writes into it.
• Statuses and modes are enums. Status, Watch, Durability, DropMode, Mood, Isolation, Transport, Engine, Modality, Role and Modification mirror the C enumerators value for value, and spell themselves through the C name tables, so nothing is compared as a string.
• Handlers cancel, and their panics resurface. A progress handler is a closure lent for one call, and a panic inside it cancels the call rather than unwinding through C, then resurfaces once the call is final.
• Borrowed pools are unsafe. Executor::on_pool takes a raw fu_pool_t, which must outlive the executor, and safe Rust has no way to check that, so it is the one unsafe constructor.

Every verb of a view defers, each on owned inputs, and borrows its arena as a blocking verb does:

• Values: write on keys beside a BytesTape, remove on keys, and read, scan, sample and measure.
• Documents: docs_write on keys beside a CharsTape of JSON, on a KeyedBy of a tape, or on keys and a CharsTape of paths beside a CharsTape of values, docs_read on keys or on keys beside a CharsTape of paths, docs_gather on a Vec<Column<'static>>, and docs_gist on keys.
• Graphs: graph_write_edges and graph_remove_edges on edges, graph_write_vertices and graph_remove_vertices on keys, and graph_read_edges and graph_degrees.
• Collections: collection_find on a String, collection_names and collection_list, and collection_drop at the head.
• Databases, transactions and snapshots: clear at the head, and compact there with a 'static progress handler or none, stage, commit, rollback and reset of a transaction, and save of a snapshot on a String, with a progress handler as compact takes one.