Crate obj 

libobj — C ABI surface for the obj embedded document database.

This crate is the unsafe boundary of obj. Every C entry point is unsafe extern "C"; internally each shim is a short piece of glue that validates pointers, calls into the safe-Rust [obj] API, and converts the obj_engine::Error result into an obj_error_t code + out-pointer.

Power-of-ten posture

• Rule 7: every fallible call inside this crate is matched or ?-propagated. No unwrap() / expect() on the C boundary; an unexpected pointer condition becomes OBJ_ERR_INVALID_ARG.
• Rule 8: the crate enables unsafe_code and turns unsafe_op_in_unsafe_fn into a hard error so every single unsafe operation lives inside an explicit unsafe { ... } block with a // SAFETY: comment justifying it against the function’s documented C contract.
• Rule 9: no dyn Trait at the C boundary. The opaque obj_db_t is a concrete struct; iterators introduced later are concrete-typed.
• Rule 10: clippy pedantic on; every #[allow(...)] carries an adjacent justification.

Pointer / lifetime conventions

• All opaque handle pointers (obj_db_t*, obj_write_txn_t*, etc.) returned by this library are obtained by leaking a Box<T>. The corresponding obj_*_close / _free / _rollback calls reclaim ownership via Box::from_raw.
• All byte buffers returned from this library are allocated as Box<[u8]> and MUST be freed via obj_free_buffer. Mixing Rust’s allocator with C’s malloc is undefined.
• Null handles are treated specifically per function: close / free / rollback are null-tolerant (no-op); every other entry point returns OBJ_ERR_INVALID_ARG when given a null handle / out-pointer.

Structs

obj_config_t

Flat C struct mirroring obj_engine::Config’s public knobs.

obj_db_t

Opaque database handle.

obj_integrity_report_t

Opaque integrity report handle. Buffers the failure list so per-failure access by index is cheap.

obj_iter_t

Opaque iterator handle returned by obj_iter_all / obj_iter_index_range. Drives one element at a time via obj_iter_next and is freed by obj_iter_free.

obj_read_txn_t

Opaque read-transaction handle. Same lifetime erasure pattern as obj_write_txn_t.

obj_stat_t

Flat C struct returned by obj_stat.

obj_write_txn_t

Opaque write-transaction handle.

Constants

OBJ_ERR_BUSY

A lock could not be acquired inside the configured timeout — another transaction holds the writer mutex / cross-process writer byte, or the in-process pager mutex was poisoned.

OBJ_ERR_CORRUPTION

Content-level corruption: a page CRC mismatch, malformed catalog row, schema-version-from-future, B-tree invariant violated, etc.

OBJ_ERR_INTEGRITY

An integrity check completed and found violations. Distinct from OBJ_ERR_CORRUPTION which is the hard fail-closed shape emitted by individual operations; OBJ_ERR_INTEGRITY is the soft “the report has failures” shape returned by aggregate diagnostic calls.

OBJ_ERR_INVALID_ARG

Caller passed an invalid argument: a null handle / out-pointer where one is required, a non-UTF-8 path or collection name, a length that exceeds the documented maximum, etc.

OBJ_ERR_IO

Underlying I/O / syscall failure: file open, read, write, fsync, directory enumeration, lock acquisition syscall.

OBJ_ERR_NOT_FOUND

The requested record / index entry / collection was not found. Iterators also return this when exhausted (see obj_iter_next docs).

OBJ_ERR_RESERVED_MAX

Highest reserved code in the obj-defined range. Future error codes must stay <= OBJ_ERR_RESERVED_MAX; this allows downstream callers to reliably distinguish obj-emitted codes from any they may layer on top.

OBJ_ERR_UNSUPPORTED

Operation is not supported in this build / for this database (e.g. obj_backup_to on an in-memory database, an attempt to mutate an attached read-only attachment, an unimplemented schema migration).

OBJ_ERR_UTF8

A C string handed across the FFI boundary was not valid UTF-8. Distinct from OBJ_ERR_INVALID_ARG because UTF-8 issues are frequent enough on user paths / index names to merit their own signal.

OBJ_OK

Operation succeeded.

OBJ_SYNC_MODE_FULL

Strongest durability — survives system-wide power loss.

OBJ_SYNC_MODE_NORMAL

Process-crash / kernel-panic durability.

OBJ_SYNC_MODE_OFF

No durability call. Tests and benchmarks only.

Functions

obj_backup_to^⚠

Take a hot backup of db to dest. The destination MUST NOT already exist.

obj_close^⚠

Close a database handle. Null-tolerant.

obj_count_all^⚠

Count every doc in collection.

obj_count_index_range^⚠

Count index B-tree entries inside [lower, upper]. Bounds use the same (ptr, len, inclusive) shape as obj_iter_index_range.

obj_doc_delete^⚠

Delete the document at id in collection. Returns OBJ_ERR_NOT_FOUND if the id is absent.

obj_doc_get^⚠

Fetch the document at id in collection. On OBJ_OK the caller owns *out_payload (length *out_payload_len) and MUST free it via obj_free_buffer. Returns OBJ_ERR_NOT_FOUND if the document is absent.

obj_doc_insert^⚠

Insert a raw-bytes document into collection. The collection is lazy-created if absent. On success *out_id is set to the freshly-allocated id.

obj_doc_update^⚠

Update the document at id in collection with payload. Returns OBJ_ERR_NOT_FOUND if the id is absent.

obj_doc_upsert^⚠

Insert-or-replace the document at id in collection with payload. The collection is lazy-created if absent.

obj_find_unique^⚠

Look up a single doc by index key on a Unique index. The caller pre-encodes key_bytes per M7’s order-preserving scheme. Returns OBJ_ERR_NOT_FOUND when no doc matches.

obj_free_buffer^⚠

Free a buffer returned by an obj_doc_get / iteration call. Pairs with the Box<[u8]>::into_raw allocation done inside [box_bytes]. Null-tolerant; passing a (ptr, len) pair that did NOT come from libobj is undefined behaviour.

obj_integrity_check^⚠

Run the full bidirectional integrity walk against db. Returns the report through *out_report. On OBJ_OK the report holds the walk’s outcome (the caller checks is_ok via obj_integrity_report_is_ok); on OBJ_ERR_INTEGRITY the walk completed but found at least one failure. Any I/O / engine error during the walk surfaces as a different error code with *out_report set to NULL.

obj_integrity_report_failure_at^⚠

Copy the Debug-formatted text of failure index into a fresh libobj-owned buffer. Caller pairs with obj_free_buffer. Returns OBJ_ERR_NOT_FOUND for an out-of-range index.

obj_integrity_report_failure_count^⚠

Number of failure entries in the report.

obj_integrity_report_free^⚠

Free an integrity report. Null-tolerant.

obj_integrity_report_is_ok^⚠

true iff the report carries no failures. Null-tolerant — returns false for a NULL report (a NULL report is by definition not a clean one).

obj_integrity_report_pages_checked^⚠

Number of pages the walker visited.

obj_iter_all^⚠

Construct an iterator over every doc in collection, snapshot- consistent against txn. Caller pairs with obj_iter_next and obj_iter_free.

obj_iter_free^⚠

Free an iterator handle. Null-tolerant.

obj_iter_index_range^⚠

Construct an iterator over the index range [lower, upper] (bounds applied per *_inclusive flag) on index_name in collection. NULL lower / upper means unbounded.

obj_iter_next^⚠

Step the iterator. On OBJ_OK the caller owns *out_payload (length *out_payload_len) and MUST free it with obj_free_buffer. Returns OBJ_ERR_NOT_FOUND at end-of- iteration; a real engine failure surfaces as the corresponding error code.

obj_open^⚠

Open or create a file-backed database at path. Default configuration (obj_engine::Config::default).

obj_open_with_config^⚠

As obj_open but with caller-supplied configuration.

obj_stat^⚠

Populate out_stat with a snapshot of the db’s header + collection-count summary.

obj_strerror^⚠

Return a static C string describing code. Never returns NULL.

obj_txn_begin_read^⚠

Begin a read transaction against db. Pins a snapshot at the current writer LSN.

obj_txn_begin_write^⚠

Begin a write transaction against db. Acquires the writer slot (subject to the configured busy timeout).

obj_txn_commit^⚠

Commit a write transaction. Consumes the handle — the C caller MUST NOT touch txn again after this returns.

obj_txn_end_read^⚠

End a read transaction. Releases the reader slot + the pinned-snapshot WAL anchor. Null-tolerant.

obj_txn_rollback^⚠

Roll back a write transaction. Null-tolerant.

Type Aliases

obj_error_t

Numeric type carried by obj_error_t. Aliased so the cbindgen header emits typedef int32_t obj_error_t; rather than a bare int32_t everywhere.

obj_sync_mode_t

SyncMode selector for obj_config_t::sync_mode.