Crate khata_rs 

khata-rs - A persisted, low-latency message queue for Rust.

A high-performance, persisted queue using memory-mapped files for low-latency reads and writes. Messages are organized into cycle files based on time (e.g., one file per day).

Features

• Low latency: Memory-mapped I/O (~3-50ns per operation)
• Persistence: All messages durably stored to disk
• Rolling files: Automatic file management based on time cycles
• Sequential access: Optimized for append and forward read patterns
• Random access: Jump to any message by index

Quick Start

use khata_rs::{Queue, Result};

fn main() -> Result<()> {
    let queue = Queue::new("/tmp/my-queue").build()?;

    // Write
    let mut writer = queue.writer()?;
    let index = writer.write(b"Hello, World!")?;

    // Read
    let mut reader = queue.reader()?;
    reader.rewind()?;
    while let Some(data) = reader.read()? {
        println!("{:?}", data);
    }

    Ok(())
}

Architecture

/queue-directory/
├── 20240125.cq4    # Cycle file for January 25, 2024
├── 20240126.cq4    # Cycle file for January 26, 2024
└── ...

Each message has a unique 64-bit index: (cycle << shift) | sequence

Roll Cycles

• FastDaily - One file per day (default)
• FastHourly - One file per hour
• FiveMinutely - One file every 5 minutes

Thread Safety

• One Writer per thread (single-producer)
• Multiple Readers can read concurrently
• Queue is Send + Sync

Re-exports

pub use cycle::FastDaily;

pub use cycle::FastHourly;

pub use cycle::FiveMinutely;

pub use cycle::HalfHourly;

pub use cycle::RollCycle;

pub use cycle::TenMinutely;

pub use index::INDEX_UNSET;

pub use index::LockFreeIndexConfig;

pub use index::LockFreeIndexing;

pub use store::FILE_HEADER_SIZE;

pub use store::Store;

pub use store::StoreConfig;

pub use store::StoreIter;

pub use util::CACHE_LINE_SIZE;

pub use util::CacheAligned;

Modules

cycle

Roll cycle definitions for khata-rs.

index

Indexing support for khata-rs.

store

Store implementation for khata-rs.

util

Low-level static utilities for performance optimization.

Structs

Queue

A persisted, low-latency message queue.

QueueBuilder

Builder for creating a Queue.

Reader

A reader for consuming messages from a Queue.

Writer

A writer for appending messages to a Queue.

Enums

Direction

Reading direction.

Error

Errors that can occur during Queue operations.

ReaderState

State of a reader in the queue.

Constants

FILE_EXTENSION

File extension for Chronicle Queue data files.

Type Aliases

Result