Struct FileStateMachine 

pub struct FileStateMachine { /* private fields */ }

File-based state machine implementation with persistence

Design principles:

• All data is persisted to disk for durability
• In-memory cache for fast read operations
• Write-ahead logging for crash consistency
• Efficient snapshot handling with file-based storage
• Thread-safe with minimal lock contention
• TTL support for automatic key expiration

Implementations

impl FileStateMachine

pub async fn new(data_dir: PathBuf) -> Result<FileStateMachine, Error>

Creates a new file-based state machine with persistence

Lease will be injected by NodeBuilder after construction.

Arguments

• data_dir - Directory where data files will be stored

Returns

Result containing the initialized FileStateMachine

pub fn set_lease(&mut self, lease: Arc<DefaultLease>)

Sets the lease manager for this state machine.

This is an internal method called by NodeBuilder during initialization. The lease will also be restored from snapshot during apply_snapshot_from_file(). Also available for testing and benchmarks.

pub async fn load_lease_data(&self) -> Result<(), Error>

Loads TTL data into the configured lease

Called after NodeBuilder injects the lease. Also available for testing and benchmarks.

pub async fn reset(&self) -> Result<(), Error>

Resets the state machine to its initial empty state

This method:

1. Clears all in-memory data
2. Resets Raft state to initial values
3. Clears all persisted files
4. Maintains operational state (running status, node ID)

Trait Implementations

impl Debug for FileStateMachine

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

Formats the value using the given formatter.

impl Drop for FileStateMachine

fn drop(&mut self)

Executes the destructor for this type.

impl StateMachine for FileStateMachine

fn apply_chunk<'life0, 'async_trait>( &'life0 self, chunk: Vec<Entry>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Thread-safe: called serially by single-task CommitHandler

fn start<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Starts the state machine service.

fn stop(&self) -> Result<(), Error>

Stops the state machine service gracefully. This is typically a sync operation for state management.

fn is_running(&self) -> bool

Checks if the state machine is currently running. Sync operation as it just checks an atomic boolean.

fn get(&self, key_buffer: &[u8]) -> Result<Option<Bytes>, Error>

Retrieves a value by key from the state machine. Sync operation as it accesses in-memory data structures.

fn entry_term(&self, entry_id: u64) -> Option<u64>

Returns the term of a specific log entry by its ID. Sync operation as it queries in-memory data.

fn len(&self) -> usize

Returns the number of entries in the state machine. NOTE: This may be expensive for some implementations. Sync operation but should be used cautiously.

fn update_last_applied(&self, last_applied: LogId)

Updates the last applied index in memory. Sync operation as it just updates atomic variables.

fn last_applied(&self) -> LogId

Gets the last applied log index and term. Sync operation as it reads from atomic variables.

fn persist_last_applied(&self, last_applied: LogId) -> Result<(), Error>

Persists the last applied index to durable storage. Should be async as it involves disk I/O.

fn update_last_snapshot_metadata( &self, snapshot_metadata: &SnapshotMetadata, ) -> Result<(), Error>

Updates snapshot metadata in memory. Sync operation as it updates in-memory structures.

fn snapshot_metadata(&self) -> Option<SnapshotMetadata>

Retrieves the current snapshot metadata. Sync operation as it reads from in-memory structures.

fn persist_last_snapshot_metadata( &self, snapshot_metadata: &SnapshotMetadata, ) -> Result<(), Error>

Persists snapshot metadata to durable storage. Should be async as it involves disk I/O.

fn apply_snapshot_from_file<'life0, 'life1, 'async_trait>( &'life0 self, metadata: &'life1 SnapshotMetadata, snapshot_dir: PathBuf, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, FileStateMachine: 'async_trait,

Applies a snapshot received from the Raft leader to the local state machine

fn generate_snapshot_data<'life0, 'async_trait>( &'life0 self, new_snapshot_dir: PathBuf, last_included: LogId, ) -> Pin<Box<dyn Future<Output = Result<Bytes, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Generates a snapshot of the state machine’s current key-value entries up to the specified last_included_index.

fn save_hard_state(&self) -> Result<(), Error>

Saves the hard state of the state machine. Sync operation as it typically just delegates to other persistence methods.

fn flush(&self) -> Result<(), Error>

Flushes any pending writes to durable storage. Sync operation that may block but provides a synchronous interface.

fn flush_async<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Flushes any pending writes to durable storage. Async operation as it involves disk I/O.

fn reset<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Resets the state machine to its initial state. Async operation as it may involve cleaning up files and data.

fn lease_background_cleanup<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<Bytes>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, FileStateMachine: 'async_trait,

Background lease cleanup hook.

fn is_empty(&self) -> bool

Checks if the state machine is empty. Sync operation that typically delegates to len().