grange-embed

name	grange-embed
description	Use grange as a LIBRARY compiled into your own machin binary rather than as a server — the module list that must be linked, the in-process API, and the gr_reset() contract. Use when building a machin app that stores documents (poche does this).

Embedding grange

grange has two consumption modes and only one speaks HTTP. poche, an agent-first CMS, compiles grange's engine into its own binary and calls it in-process. If you are writing a machin app that needs storage, this is usually the mode you want: no second process, no port, no token.

The module list is a contract, not a suggestion

grange's modules call each other, so a subset either resolves or does not compile at all. Link all of these:

src/engine.src  src/registry.src
src/cold.src    src/coldindex.src  src/coldrange.src  src/coldsort.src
src/index.src   src/range.src      src/qcost.src      src/query.src
src/order.src

Dropping one is not "fewer features" — it is a build error like undefined variable "g_cifields". poche's build broke exactly this way when grange added cross-module calls, and stayed broken until someone rebuilt it, because nothing in grange's own gate compiled a subset. scripts/embed_test.sh (make embed) now pins the list; keep your build in sync with it.

Build against a sibling checkout rather than vendoring, so a grange fix reaches you:

GRANGE_SRC="${GRANGE_SRC:-$ROOT/../grange/src}"

The in-process API

gr_use(db, coll)          -> (ok, errmsg)   open/switch collection
gr_put(id, doc)                             stage a write
gr_del(id)                                  stage a delete
gr_commit()               -> ok             durable (fsynced) on return
gr_index_add(field, sums, kind)             kind "range" for ordering/cursors
q_find(where, limit)      -> json
q_count(where)            -> json
q_find_page(where, limit, order, desc, after) -> (json, ok, why)
gr_verify(deep)           -> (json, issues)
gr_compact()

Query semantics are identical to the served ones — see grange-query.

gr_reset(): the contract that will bite you

gr_reset() commits pending writes, drops every in-memory cache and frees the arena. It is how a long-lived embedder keeps RSS flat (poche calls it every N requests) — grange's own server leaves it off by default.

It frees the arena, so it invalidates everything the CALLER is still holding, not just grange's internals. A string read out of a query before the reset is garbage after it:

count before reset: 60
count after  reset: 0<garbage>     // same variable, freed memory

Call it only where nothing is in flight: after the response is written, with no parked watchers (they hold collection names) and no staged writes.

The same hazard applies to your own globals. Across an arena reset, string LITERALS, env() values and args() values survive; computed strings are silently corrupted (machin#540). Re-derive anything else from args()/env() directly — not from a parsed flag struct, whose internal maps are themselves computed. grange re-initialises its own bytes("\n") separator inside gr_reset() for this reason: without it every page walk searched for garbage, pages read as empty, and only the integrity checker noticed.

Storage mode

A collection is hot (whole dataset in memory) or cold (disk-resident pages). Embedders default to hot, which is right for CMS-sized data; call the cold conversion for archival collections. See grange-operate.