Struct corundum::Journal

pub struct Journal<A: MemPool> { /* private fields */ }

A Journal object to be used for writing logs onto

Each transaction, hence each thread, may have only one journal for every memory pool to write the logs. The journal itself resides in a pool. Journals are linked together in the MemPool object to be accessible in recovery procedure.

It is not allowed to create a Journal object. However, transaction() creates a journal at the beginning and passes a reference to it to the body closure. So, to obtain a reference to a Journal, you may wrap a transaction around your code. For example:

use corundum::alloc::heap::*;

let cell = Heap::transaction(|journal| {
    let cell = Pbox::new(PCell::new(10), journal);
 
    assert_eq!(cell.get(), 10);
}).unwrap();

A Journal consists of one or more pages. A page provides a fixed number of log slots which is specified by PAGE_SIZE (64). This helps performance as the logs are pre-allocated. When the number of logs in a page exceeds 64, Journal object atomically allocate a new page for another 64 pages before running the operations.

Journals by default are deallocated after the transaction or recovery. However, it is possible to pin journals in the pool if they are used frequently by enabling “pin_journals” feature.

Implementations

impl<A: MemPool> Journal<A>

pub unsafe fn new(gen: u32) -> Self

Create new Journal with default values

pub fn gen(&self) -> u32

Returns the generation number of this journal

pub fn is_committed(&self) -> bool

Returns true if the journal is committed

pub unsafe fn set(&mut self, flag: u64)

Sets a flag

pub unsafe fn unset(&mut self, flag: u64)

Resets a flag

pub fn is_set(&self, flag: u64) -> bool

Checks a flag

pub unsafe fn enter_into(&mut self, head_off: &u64, zone: usize)

Atomically enters into the list journals of the owner pool

pub fn recovery_info(&self, info_level: u32) -> String

Returns a string containing the logging information

pub unsafe fn commit(&mut self)

Commits all logs in the journal

pub unsafe fn rollback(&mut self)

Reverts all changes

pub unsafe fn recover(&mut self)

Recovers from a crash or power failure

pub unsafe fn clear(&mut self)

Clears all logs and drops itself from the memory pool

pub fn resume(&self) -> bool

Determines whether to fast-forward or rollback the transaction on recovery according to the following table:

 ┌───────────┬────────────┬──────────┬─────┐
 │ Committed │ Chaperoned │ Complete │  FF │
 ╞═══════════╪════════════╪══════════╪═════╡
 │    TRUE   │    FALSE   │     X    │ YES │
 │    TRUE   │    TRUE    │   TRUE   │ YES │
 │    TRUE   │    TRUE    │   FALSE  │  NO │
 │   FALSE   │      X     │     X    │  NO │
 └───────────┴────────────┴──────────┴─────┘

Fast-forward means that no matter the transaction is committed or not, if there exist logs, discard them all without rolling back.

States:

• Committed: Transaction is already committed but not complete (Logs still exist).
• Chaperoned: The transaction was attached to a Chaperon::transaction.
• Complete: The Chaperon::transaction is complete.

pub unsafe fn next_off(&self) -> u64

Returns the offset of the next journal, if any. Otherwise, returns u64::MAX

pub unsafe fn prev_off(&self) -> u64

Returns the offset of the previous journal, if any. Otherwise, returns u64::MAX

pub unsafe fn next_off_ref(&self) -> &u64

pub unsafe fn prev_off_ref(&self) -> &u64

pub unsafe fn current(create: bool) -> Option<(*const Journal<A>, *mut i32)> where
    Self: Sized, 

Returns a journal for the current thread. If there is no Journal object for the running thread, it may create a new journal and returns its mutable reference. Each thread may have only one journal.

pub fn is_running() -> bool

Returns true if there is a running transaction on the current thread

pub unsafe fn ignore(&self)

Ignores all logs

This function is only for measuring some properties such as log latency.

Trait Implementations

impl<A: MemPool> Debug for Journal<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: MemPool> !LooseTxInUnsafe for Journal<A>

impl<A: MemPool> !PSafe for Journal<A>

impl<A: MemPool> !RefUnwindSafe for Journal<A>

impl<A: MemPool> !Send for Journal<A>

impl<A: MemPool> !Sync for Journal<A>

impl<A: MemPool> !TxInSafe for Journal<A>

impl<A: MemPool> !TxOutSafe for Journal<A>

impl<A: MemPool> !UnwindSafe for Journal<A>