102 lines
3.8 KiB
Rust
102 lines
3.8 KiB
Rust
//! alkstore-mem — the mem engine: the core contract implemented on
|
|
//! guarded in-memory state, process-owned (ADR-001, ADR-024).
|
|
//!
|
|
//! # Posture
|
|
//!
|
|
//! **Honest-ephemeral** (ADR-016 carriers, ADR-024 §2): no durability,
|
|
//! single-process, ephemeral by design — a legitimate production
|
|
//! choice for workloads that accept ephemerality, and never fleet-valid
|
|
//! (the shared-pool predicate fails structurally — there is no pool).
|
|
//! The dependency on `alkstore-mem` *is* the ephemerality declaration;
|
|
//! compile-time engine identity (this crate) carries the honesty —
|
|
//! no runtime surface is fabricated to detect it. Each
|
|
//! [`MemStore::new`] yields a fully isolated instance sharing nothing;
|
|
//! teardown is drop, and engine drop closes open receivers.
|
|
//!
|
|
//! **Full contract v1** (ADR-024 §3): every mechanism, every guarantee
|
|
//! row — the queue state machine, the scheduler collapse, streams with
|
|
//! per-consumer offsets and trim, TTL locks, the tx seam, wakes. Born
|
|
//! pinned: the contract suite's third `StoreFactory` column (ADR-022)
|
|
//! runs this engine under a current-thread runtime flavor.
|
|
//!
|
|
//! **wasm32** (ADR-024 §5): this crate compiles clean for
|
|
//! `wasm32-unknown-unknown` — tokio restricted to the wasm-supported
|
|
//! subset (sync + time), no driver dependencies, no `spawn_blocking`
|
|
//! anywhere; internals are current-thread-runtime-clean by
|
|
//! construction. Every timestamp reads the process clock through one
|
|
//! internal accessor (no server clock to defer to).
|
|
//!
|
|
//! # Architecture
|
|
//!
|
|
//! The store instance *is* the state: guarded per-mechanism sections
|
|
//! behind short-held synchronous internal locks,
|
|
//! tokio primitives for cross-await coordination. The tx seam is an
|
|
//! overlay (`tx` — stage in the handle-private overlay, commit
|
|
//! merges atomically + wakes at commit, drop discards); wakes route
|
|
//! through in-process channels (`wakes`) — delivered at the
|
|
//! commit boundary directly to each open receiver, per-subscriber FIFO
|
|
//! by commit order, never coalesced (no batching boundary exists).
|
|
//!
|
|
//! # Example
|
|
//!
|
|
//! The honest-ephemeral engine is the zero-config one, so this crate
|
|
//! carries the contract round-trip example: open with one call,
|
|
//! enqueue a job, claim it back (the other engines construct through
|
|
//! their `open` form with a connection target and opts — the surface
|
|
//! round-trip below is identical there).
|
|
//!
|
|
//! ```
|
|
//! use alkstore::{EnqueueOpts, JobHandle, QueueOpts, Store};
|
|
//! use alkstore_mem::MemStore;
|
|
//!
|
|
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let rt = tokio::runtime::Builder::new_current_thread().build()?;
|
|
//! let store = MemStore::new();
|
|
//! let queue = rt.block_on(store.queue("demo", QueueOpts::default()))?;
|
|
//! let job_id = rt.block_on(queue.enqueue(
|
|
//! serde_json::json!("hello"),
|
|
//! EnqueueOpts::default(),
|
|
//! ))?;
|
|
//! let claimed = rt.block_on(queue.claim_one("worker-1"))?
|
|
//! .expect("the enqueued job is claimable");
|
|
//! assert_eq!(claimed.job().id, job_id);
|
|
//! assert_eq!(claimed.job().state, alkstore::JobState::Processing);
|
|
//! # Ok(())
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! Every public item carries doc text; the missing-docs lint is part
|
|
//! of the standing gates.
|
|
|
|
#![warn(missing_docs)]
|
|
|
|
mod clock;
|
|
mod lock;
|
|
mod notify;
|
|
mod outbox;
|
|
mod queue;
|
|
mod resolution;
|
|
mod scheduler;
|
|
mod state;
|
|
mod store;
|
|
mod stream;
|
|
mod tx;
|
|
mod validation;
|
|
mod wakes;
|
|
|
|
#[cfg(test)]
|
|
mod fuzz_surface_tests;
|
|
|
|
pub use store::MemStore;
|
|
|
|
/// Fuzz/test-only surface: the mem engine's `@every` parser — not
|
|
/// contract surface, not consumer API, no stability guarantee.
|
|
#[doc(hidden)]
|
|
pub use scheduler::parse_every_interval;
|
|
|
|
/// Fuzz/test-only surface: the mem engine's schedule skip-forward
|
|
/// arithmetic — not contract surface, not consumer API, no stability
|
|
/// guarantee.
|
|
#[doc(hidden)]
|
|
pub use scheduler::skip_forward;
|