Ṛta (ऋत)

Ṛta (ऋत) is a minimal metadata store for durable system state.

Usage

Add following to your Cargo.toml,

[dependencies]
rta = { version = "0.0.3" }

Note

Current rta requires Rust 1.86 or later.

The type T

T must satisfy following layout and safety constraints:

• Implements RTA
• Uses #[repr(C)]
• 8 bytes alignment
• Does not implements Drop
• Size must be >0 and multiple of 8
• Implements Default + Clone + Send + Sync + 'static

Requirements for type T

The type T must not,

• Have any non-deterministic feilds
• Have interior pointers or self-references
• Have changes made to the layout after Rta::init()

Write

The Rta::write is designed as a lightweight fire and forget metadata update premitive. The call itself does not wait for the filesystem durability, allowing sub-mirco second write latency.

Apps requireing stronger durability can explicitly wait or block on the returned frozen_core::ack::AckTicket using either the asynchronous await interface or the internal blocking wait() api.

Every write guarantees,

• Serialized object updates
• Crash-safe durability using multiple on-disk copies
• Automatic recovery from torn or interrupted writes by selecting the newest valid version during initialization

Observed measurements for latency (both single and multi-threaded) on 1,048,576 operations,

Metric	Single TX (µs)	Multi TX (µs)
P50	0.1830	0.4590
P90	0.2750	0.7330
P99	1216.5110	1.0090
Mean	38.0899	8.7255
Max	28606.4630	21790.7190

Observed measurements for latency (both single and multi-threaded) on 4,096 operations, where every write waits for filesystem durability,

Metric	Single TX (ms)	Multi TX (ms)
P50	1.1899	1.2820
P90	1.2902	2.8078
P99	1.5165	5.2634
Mean	1.1885	1.7603
Max	31.3917	30.1793

Read

The Rta::read is a wait-free fast-path read which reads the most recently updated T directly from the underlying memory mapping.

A successful read reflects the latest published write, but does not imply that the object has been durably persisted to the filesystem. To guarantee durability, wait on the ticket returned by Rta::write.

Observed measurements for latency (both single and multi threaded) on 1,048,576 individual ops,

Metric	Single TX (µs)	Multi TX (µs)
P50	0.0000	0.0910
P90	0.0910	0.1830
P99	0.0920	0.8210
MEAN	0.0205	0.1362
MAX	38.0790	5013.5030

Example

use rta::{RTA, Rta, RtaCfg};

#[repr(C)]
#[repr(align(8))]
#[derive(Debug, Clone, Default, RTA)]
struct Config {
    value: u64,
}

let dir = tempfile::tempdir().expect("failed to create temp directory");
let rta = Rta::<Config>::new(RtaCfg {
    module_id: 0,
    copies_on_disk: 4,
    path: dir.path().join("config.rta"),
})
.expect("failed to create RTA");

let ticket = unsafe {
    rta.write(|cfg| {
        cfg.value = 0x2A;
    })
}
.expect("write failed");
ticket.wait().expect("durability failed");

let cfg = unsafe { rta.read() };
assert_eq!(cfg.value, 0x2A);

Etymology

ऋत (transliterated as Ṛta) is a vedic concept of cosmic order, truth, and invariance that inspired the design of Ṛta crate.