Struct Log 

pub struct Log { /* private fields */ }

Caller-owned heap history with fixed limits and monotonic append watermarks.

Implementations

impl Log

pub const fn new(limits: Limits) -> Self

Construct an empty log without preallocating the configured maximum.

Examples found in repository

examples/worker.rs (lines 7-11)

fn main() {
    let mut log = Log::new(Limits {
        max_entries: NonZeroUsize::new(8).expect("positive capacity"),
        max_message_bytes: 32,
        max_label_bytes: 16,
    });
    for (created_at_secs, level, message) in [
        (10, Level::Info, "delivery accepted"),
        (
            11,
            Level::Warn,
            "provider reply is still unknown; reconcile before retry",
        ),
        (12, Level::Ok, "original delivery reconciled"),
    ] {
        log.append(EntryInput {
            created_at_secs,
            level,
            source: "worker",
            topic: Some("delivery"),
            message,
        })
        .expect("valid bounded entry");
    }
    let page = log.page(
        Filter::default(),
        PageRequest {
            before: None,
            max_results: NonZeroUsize::new(8).expect("positive results"),
            max_scanned: NonZeroUsize::new(8).expect("positive scan"),
        },
    );
    for entry in page.entries {
        println!("{} {:?}: {}", entry.sequence, entry.level, entry.message);
    }
    let batch = log.prune_expired(16, 5, 1);
    assert_eq!(batch.removed, 1);
    assert_eq!(log.next_expiry_secs(5), Some(17));
}

pub const fn limits(&self) -> Limits

Return the fixed bounds without copying retained messages.

pub fn snapshot(&self) -> LogSnapshot

Copy all retained rows and both append watermarks for explicit checkpointing. Work and allocation scale with retained history, not a cursor-page limit.

pub fn restore(snapshot: LogSnapshot) -> Result<Self, RestoreError>

Admit a complete checkpoint without replaying entries or reissuing identities.

Empty retained history preserves its original append watermarks. Admission proves internal consistency, not source authenticity or host continuity. Byte decoders must bound allocation before constructing the checkpoint.

Errors

Rejects bounds, row ordering, watermarks and truncation states that cannot result from this engine’s append/retention operations.

pub fn len(&self) -> usize

Return the retained row count.

pub fn is_empty(&self) -> bool

Whether this log currently has no retained rows.

pub fn append(&mut self, input: EntryInput<'_>) -> Result<u64, AppendError>

Admit one row and evict the oldest if the count ceiling is reached.

Errors

Returns a typed refusal for oversized labels, regressed time or exhausted sequence identities. Validation completes before any eviction or mutation.

Examples found in repository

examples/worker.rs (lines 21-27)

fn main() {
    let mut log = Log::new(Limits {
        max_entries: NonZeroUsize::new(8).expect("positive capacity"),
        max_message_bytes: 32,
        max_label_bytes: 16,
    });
    for (created_at_secs, level, message) in [
        (10, Level::Info, "delivery accepted"),
        (
            11,
            Level::Warn,
            "provider reply is still unknown; reconcile before retry",
        ),
        (12, Level::Ok, "original delivery reconciled"),
    ] {
        log.append(EntryInput {
            created_at_secs,
            level,
            source: "worker",
            topic: Some("delivery"),
            message,
        })
        .expect("valid bounded entry");
    }
    let page = log.page(
        Filter::default(),
        PageRequest {
            before: None,
            max_results: NonZeroUsize::new(8).expect("positive results"),
            max_scanned: NonZeroUsize::new(8).expect("positive scan"),
        },
    );
    for entry in page.entries {
        println!("{} {:?}: {}", entry.sequence, entry.level, entry.message);
    }
    let batch = log.prune_expired(16, 5, 1);
    assert_eq!(batch.removed, 1);
    assert_eq!(log.next_expiry_secs(5), Some(17));
}

pub fn prune_expired( &mut self, now_secs: u64, max_age_secs: u64, max_remove: usize, ) -> RetentionBatch

Remove at most max_remove entries strictly older than the age cutoff. An entry remains available through its full configured age second.

Examples found in repository

examples/worker.rs (line 41)

fn main() {
    let mut log = Log::new(Limits {
        max_entries: NonZeroUsize::new(8).expect("positive capacity"),
        max_message_bytes: 32,
        max_label_bytes: 16,
    });
    for (created_at_secs, level, message) in [
        (10, Level::Info, "delivery accepted"),
        (
            11,
            Level::Warn,
            "provider reply is still unknown; reconcile before retry",
        ),
        (12, Level::Ok, "original delivery reconciled"),
    ] {
        log.append(EntryInput {
            created_at_secs,
            level,
            source: "worker",
            topic: Some("delivery"),
            message,
        })
        .expect("valid bounded entry");
    }
    let page = log.page(
        Filter::default(),
        PageRequest {
            before: None,
            max_results: NonZeroUsize::new(8).expect("positive results"),
            max_scanned: NonZeroUsize::new(8).expect("positive scan"),
        },
    );
    for entry in page.entries {
        println!("{} {:?}: {}", entry.sequence, entry.level, entry.message);
    }
    let batch = log.prune_expired(16, 5, 1);
    assert_eq!(batch.removed, 1);
    assert_eq!(log.next_expiry_secs(5), Some(17));
}

pub fn next_expiry_secs(&self, max_age_secs: u64) -> Option<u64>

First second at which the oldest row expires; None for empty history or overflow.

Examples found in repository

examples/worker.rs (line 43)

fn main() {
    let mut log = Log::new(Limits {
        max_entries: NonZeroUsize::new(8).expect("positive capacity"),
        max_message_bytes: 32,
        max_label_bytes: 16,
    });
    for (created_at_secs, level, message) in [
        (10, Level::Info, "delivery accepted"),
        (
            11,
            Level::Warn,
            "provider reply is still unknown; reconcile before retry",
        ),
        (12, Level::Ok, "original delivery reconciled"),
    ] {
        log.append(EntryInput {
            created_at_secs,
            level,
            source: "worker",
            topic: Some("delivery"),
            message,
        })
        .expect("valid bounded entry");
    }
    let page = log.page(
        Filter::default(),
        PageRequest {
            before: None,
            max_results: NonZeroUsize::new(8).expect("positive results"),
            max_scanned: NonZeroUsize::new(8).expect("positive scan"),
        },
    );
    for entry in page.entries {
        println!("{} {:?}: {}", entry.sequence, entry.level, entry.message);
    }
    let batch = log.prune_expired(16, 5, 1);
    assert_eq!(batch.removed, 1);
    assert_eq!(log.next_expiry_secs(5), Some(17));
}

pub fn page(&self, filter: Filter<'_>, request: PageRequest) -> Page<'_>

Scan newest-first without cloning retained messages or counting every match. Follow next_before with the same filters, including after an empty page.

Examples found in repository

examples/worker.rs (lines 30-37)

fn main() {
    let mut log = Log::new(Limits {
        max_entries: NonZeroUsize::new(8).expect("positive capacity"),
        max_message_bytes: 32,
        max_label_bytes: 16,
    });
    for (created_at_secs, level, message) in [
        (10, Level::Info, "delivery accepted"),
        (
            11,
            Level::Warn,
            "provider reply is still unknown; reconcile before retry",
        ),
        (12, Level::Ok, "original delivery reconciled"),
    ] {
        log.append(EntryInput {
            created_at_secs,
            level,
            source: "worker",
            topic: Some("delivery"),
            message,
        })
        .expect("valid bounded entry");
    }
    let page = log.page(
        Filter::default(),
        PageRequest {
            before: None,
            max_results: NonZeroUsize::new(8).expect("positive results"),
            max_scanned: NonZeroUsize::new(8).expect("positive scan"),
        },
    );
    for entry in page.entries {
        println!("{} {:?}: {}", entry.sequence, entry.level, entry.message);
    }
    let batch = log.prune_expired(16, 5, 1);
    assert_eq!(batch.removed, 1);
    assert_eq!(log.next_expiry_secs(5), Some(17));
}

Trait Implementations

impl Debug for Log

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

Formats the value using the given formatter.