Module sequence 

Sequence number allocation and persistence.

This module provides components for allocating monotonically increasing sequence numbers with crash recovery. It provides:

SequenceAllocator: Allocates individual sequence numbers from sequence blocks stored in storage. Tracks the current reserved block, and allocates new sequence numbers from it. When the block is out of sequence numbers, the allocator allocates a new block, and returns the corresponding Record in the return from SequenceAllocator#allocate. It is up to the caller to ensure that the record is persisted in storage. This allows the allocator to be used from implementations of Delta by including the sequence block writes in persisted deltas.

Design

Block-based allocation reduces write amplification by pre-allocating ranges of sequence numbers instead of persisting after every allocation. The allocator tracks allocations via SeqBlock records:

• base_sequence: Starting sequence number of the allocated block
• block_size: Number of sequence numbers in the block

On crash recovery, the next block starts at base_sequence + block_size, ensuring monotonicity even if some allocated sequences were unused.

Usage

Each system provides its own key format for storing the SeqBlock record:

use bytes::Bytes;
use common::sequence::{SeqBlockStore, SequenceAllocator};

// Domain-specific key (e.g., Log uses [0x01, 0x02])
const MY_SEQ_BLOCK_KEY: &[u8] = &[0x01, 0x02];

let key = Bytes::from_static(MY_SEQ_BLOCK_KEY);
let allocator = SequenceAllocator::load(storage.clone(), key);

let (seq, put) = allocator.allocate_one().await?;
if let Some(put) = put {
    storage.put(vec![put]).await.unwrap();
}

Structs

AllocatedSeqBlock

SequenceAllocator

Allocates sequence numbers from pre-allocated blocks.

Enums

SequenceError

Error type for sequence allocation operations.

Constants

DEFAULT_BLOCK_SIZE

Default block size for sequence allocation.

Type Aliases

SequenceResult

Result type alias for sequence allocation operations.