Struct FMTransaction 

pub struct FMTransaction<'a, T> { /* private fields */ }

A context for grouping multi write ops into a single atomic operation

Overview

Use of FMTransaction allows to group multiple write ops into a single atomic operation.

• All included writes are applied together
• Single epoch is assinged for an entier transaction
• Durability guarantee is same for all included write ops

Example

use frozen_core::fmmap::{FrozenMMap, FrozenMMapCfg};

const MODULE_ID: u8 = 0;

let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("tmp_tx");

let cfg = FrozenMMapCfg {
    module_id: MODULE_ID,
    initial_count: 0x0A,
    flush_duration: std::time::Duration::from_micros(50),
};

let mmap = FrozenMMap::<u64>::new(&path, cfg).unwrap();

let mut tx = mmap.new_tx();
unsafe { tx.write(0, |v| *v = 0x0A) }.unwrap();
unsafe { tx.write(1, |v| *v = 0x14) }.unwrap();
unsafe { tx.write(2, |v| *v = 0x18) }.unwrap();

let epoch = tx.commit().unwrap();
mmap.wait_for_durability(epoch).unwrap();

let v0 = unsafe { mmap.read(0, |v| *v).unwrap() };
let v1 = unsafe { mmap.read(1, |v| *v).unwrap() };
let v2 = unsafe { mmap.read(2, |v| *v).unwrap() };

assert_eq!((v0, v1, v2), (0x0A, 0x14, 0x18));

Implementations

impl<'a, T> FMTransaction<'a, T>

pub unsafe fn write<F>(&mut self, index: usize, f: F) -> FrozenResult<()>

where F: FnOnce(*mut T) + 'a,

Append a write op into the FMTransaction

Requirements

Write ops must follow these safety requirements,

• No duplicate indices
• No out-of-order writes (must be incremental)

Violating this constraint would result in FrozenError

Safety

Same safety requirements as FrozenMMap::write apply here

Example

use frozen_core::fmmap::{FrozenMMap, FrozenMMapCfg};

const MODULE_ID: u8 = 0;

let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("tmp_tx");

let cfg = FrozenMMapCfg {
    module_id: MODULE_ID,
    initial_count: 0x10,
    flush_duration: std::time::Duration::from_micros(50),
};

let mmap = FrozenMMap::<u64>::new(&path, cfg).unwrap();

let mut tx = mmap.new_tx();
unsafe { tx.write(0, |v| *v = 0x0A) }.unwrap();
unsafe { tx.write(1, |v| *v = 0x0B) }.unwrap();
unsafe { tx.write(2, |v| *v = 0x0C) }.unwrap();

let epoch = tx.commit().unwrap();
mmap.wait_for_durability(epoch).unwrap();

let v0 = unsafe { mmap.read(0, |v| *v).unwrap() };
let v1 = unsafe { mmap.read(1, |v| *v).unwrap() };
let v2 = unsafe { mmap.read(2, |v| *v).unwrap() };

assert_eq!((v0, v1, v2), (0x0A, 0x0B, 0x0C));

pub fn commit(self) -> FrozenResult<u64>

Commit the transaction, applying all the writes ops, combined into a single atomic operation

Guarantees

• All writes are applied under a single epoch
• All writes belong to the same durability batch
• No interleaving with other transactions at epoch level

Example

use frozen_core::fmmap::{FrozenMMap, FrozenMMapCfg};

const MODULE_ID: u8 = 0;

let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("tmp_tx");

let cfg = FrozenMMapCfg {
    module_id: MODULE_ID,
    initial_count: 0x10,
    flush_duration: std::time::Duration::from_micros(50),
};

let mmap = FrozenMMap::<u64>::new(&path, cfg).unwrap();

let mut tx = mmap.new_tx();
unsafe { tx.write(0, |v| *v = 0x0A) }.unwrap();
unsafe { tx.write(2, |v| *v = 0x0C) }.unwrap();

let epoch = tx.commit().unwrap();
mmap.wait_for_durability(epoch).unwrap();

let v0 = unsafe { mmap.read(0, |v| *v).unwrap() };
let v1 = unsafe { mmap.read(2, |v| *v).unwrap() };

assert_eq!((v0, v1), (0x0A, 0x0C));