khata_rs/lib.rs
1//! khata-rs - A persisted, low-latency message queue for Rust.
2//!
3//! A high-performance, persisted queue using memory-mapped files for
4//! low-latency reads and writes. Messages are organized into cycle files
5//! based on time (e.g., one file per day).
6//!
7//! # Features
8//!
9//! - **Low latency**: Memory-mapped I/O (~3-50ns per operation)
10//! - **Persistence**: All messages durably stored to disk
11//! - **Rolling files**: Automatic file management based on time cycles
12//! - **Sequential access**: Optimized for append and forward read patterns
13//! - **Random access**: Jump to any message by index
14//!
15//! # Quick Start
16//!
17//! ```no_run
18//! use khata_rs::{Queue, Result};
19//!
20//! fn main() -> Result<()> {
21//! let queue = Queue::new("/tmp/my-queue").build()?;
22//!
23//! // Write
24//! let mut writer = queue.writer()?;
25//! let index = writer.write(b"Hello, World!")?;
26//!
27//! // Read
28//! let mut reader = queue.reader()?;
29//! reader.rewind()?;
30//! while let Some(data) = reader.read()? {
31//! println!("{:?}", data);
32//! }
33//!
34//! Ok(())
35//! }
36//! ```
37//!
38//! # Architecture
39//!
40//! ```text
41//! /queue-directory/
42//! ├── 20240125.cq4 # Cycle file for January 25, 2024
43//! ├── 20240126.cq4 # Cycle file for January 26, 2024
44//! └── ...
45//! ```
46//!
47//! Each message has a unique 64-bit index: `(cycle << shift) | sequence`
48//!
49//! # Roll Cycles
50//!
51//! - [`FastDaily`] - One file per day (default)
52//! - [`FastHourly`] - One file per hour
53//! - [`FiveMinutely`] - One file every 5 minutes
54//!
55//! # Thread Safety
56//!
57//! - One [`Writer`] per thread (single-producer)
58//! - Multiple [`Reader`]s can read concurrently
59//! - [`Queue`] is `Send + Sync`
60
61mod error;
62mod queue;
63mod reader;
64mod writer;
65
66pub mod cycle;
67pub mod index;
68pub mod store;
69pub mod util;
70
71// Primary API - simple names at crate root
72pub use cycle::{FastDaily, FastHourly, FiveMinutely, HalfHourly, RollCycle, TenMinutely};
73pub use error::{Error, Result};
74pub use index::{INDEX_UNSET, LockFreeIndexConfig, LockFreeIndexing};
75pub use queue::{FILE_EXTENSION, Queue, QueueBuilder};
76pub use reader::{Direction, Reader, ReaderState};
77pub use store::{FILE_HEADER_SIZE, Store, StoreConfig, StoreIter};
78pub use util::{CACHE_LINE_SIZE, CacheAligned};
79pub use writer::Writer;