[−][src]Trait async_raft::storage::RaftStorage
A trait defining the interface for a Raft storage system.
See the storage chapter of the guide for details and discussion on this trait and how to implement it.
Associated Types
type Snapshot: AsyncRead + AsyncWrite + AsyncSeek + Send + Unpin + 'static[src]
The storage engine's associated type used for exposing a snapshot for reading & writing.
Required methods
#[must_use]pub fn get_membership_config<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<MembershipConfig>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<MembershipConfig>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Get the latest membership config found in the log.
This must always be implemented as a reverse search through the log to find the most recent membership config to be appended to the log.
If a snapshot pointer is encountered, then the membership config embedded in that snapshot pointer should be used.
If the system is pristine, then it should return the value of calling
MembershipConfig::new_initial(node_id). It is required that the storage engine persist
the node's ID so that it is consistent across restarts.
#[must_use]pub fn get_initial_state<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<InitialState>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<InitialState>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Get Raft's state information from storage.
When the Raft node is first started, it will call this interface on the storage system to
fetch the last known state from stable storage. If no such entry exists due to being the
first time the node has come online, then InitialState::new_initial should be used.
pro tip
The storage impl may need to look in a few different places to accurately respond to this
request: the last entry in the log for last_log_index & last_log_term; the node's hard
state record; and the index of the last log applied to the state machine.
#[must_use]pub fn save_hard_state<'life0, 'life1, 'async_trait>(
&'life0 self,
hs: &'life1 HardState
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
hs: &'life1 HardState
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Save Raft's hard-state.
#[must_use]pub fn get_log_entries<'life0, 'async_trait>(
&'life0 self,
start: u64,
stop: u64
) -> Pin<Box<dyn Future<Output = Result<Vec<Entry<D>>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
start: u64,
stop: u64
) -> Pin<Box<dyn Future<Output = Result<Vec<Entry<D>>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Get a series of log entries from storage.
The start value is inclusive in the search and the stop value is non-inclusive: [start, stop).
#[must_use]pub fn delete_logs_from<'life0, 'async_trait>(
&'life0 self,
start: u64,
stop: Option<u64>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
start: u64,
stop: Option<u64>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Delete all logs starting from start and stopping at stop, else continuing to the end
of the log if stop is None.
#[must_use]pub fn append_entry_to_log<'life0, 'life1, 'async_trait>(
&'life0 self,
entry: &'life1 Entry<D>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
entry: &'life1 Entry<D>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Append a new entry to the log.
#[must_use]pub fn replicate_to_log<'life0, 'life1, 'async_trait>(
&'life0 self,
entries: &'life1 [Entry<D>]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
entries: &'life1 [Entry<D>]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Replicate a payload of entries to the log.
Though the entries will always be presented in order, each entry's index should be used to determine its location to be written in the log.
#[must_use]pub fn apply_entry_to_state_machine<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
index: &'life1 u64,
data: &'life2 D
) -> Pin<Box<dyn Future<Output = Result<R>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
index: &'life1 u64,
data: &'life2 D
) -> Pin<Box<dyn Future<Output = Result<R>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
Apply the given log entry to the state machine.
The Raft protocol guarantees that only logs which have been committed, that is, logs which have been replicated to a majority of the cluster, will be applied to the state machine.
This is where the business logic of interacting with your application's state machine should live. This is 100% application specific. Perhaps this is where an application specific transaction is being started, or perhaps committed. This may be where a key/value is being stored. This may be where an entry is being appended to an immutable log.
The behavior here is application specific, but errors should never be returned unless the
error represents an actual failure to apply the entry. An error returned here will cause
the Raft node to shutdown in order to preserve the safety of the data and avoid corruption.
If instead some application specific error needs to be returned to the client, those
variants must be encapsulated in the type R, which may have application specific success
and error variants encoded in the type, perhaps using an inner Result type.
#[must_use]pub fn replicate_to_state_machine<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
entries: &'life1 [(&'life2 u64, &'life3 D)]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
entries: &'life1 [(&'life2 u64, &'life3 D)]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Self: 'async_trait,
Apply the given payload of entries to the state machine, as part of replication.
The Raft protocol guarantees that only logs which have been committed, that is, logs which have been replicated to a majority of the cluster, will be applied to the state machine.
#[must_use]pub fn do_log_compaction<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<CurrentSnapshotData<Self::Snapshot>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<CurrentSnapshotData<Self::Snapshot>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Perform log compaction, returning a handle to the generated snapshot.
implementation guide
When performing log compaction, the compaction can only cover the breadth of the log up to the last applied log and under write load this value may change quickly. As such, the storage implementation should export/checkpoint/snapshot its state machine, and then use the value of that export's last applied log as the metadata indicating the breadth of the log covered by the snapshot.
#[must_use]pub fn create_snapshot<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<(String, Box<Self::Snapshot>)>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<(String, Box<Self::Snapshot>)>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Create a new blank snapshot, returning a writable handle to the snapshot object along with the ID of the snapshot.
implementation guide
See the storage chapter of the guide for details on log compaction / snapshotting.
#[must_use]pub fn finalize_snapshot_installation<'life0, 'async_trait>(
&'life0 self,
index: u64,
term: u64,
delete_through: Option<u64>,
id: String,
snapshot: Box<Self::Snapshot>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self,
index: u64,
term: u64,
delete_through: Option<u64>,
id: String,
snapshot: Box<Self::Snapshot>
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Finalize the installation of a snapshot which has finished streaming from the cluster leader.
Delete all entries in the log through delete_through, unless None, in which case
all entries of the log are to be deleted.
Write a new snapshot pointer to the log at the given index. The snapshot pointer should be
constructed via the Entry::new_snapshot_pointer constructor and the other parameters
provided to this method.
All other snapshots should be deleted at this point.
snapshot
A snapshot created from an earlier call to created_snapshot which provided the snapshot.
By the time ownership of the snapshot object is returned here, its
AsyncWriteExt.shutdown() method will have been called, so no additional writes should be
made to the snapshot.
#[must_use]pub fn get_current_snapshot<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<Option<CurrentSnapshotData<Self::Snapshot>>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait, [src]
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<Option<CurrentSnapshotData<Self::Snapshot>>>> + Send + 'async_trait>> where
'life0: 'async_trait,
Self: 'async_trait,
Get a readable handle to the current snapshot, along with its metadata.
implementation algorithm
Implementing this method should be straightforward. Check the configured snapshot directory for any snapshot files. A proper implementation will only ever have one active snapshot, though another may exist while it is being created. As such, it is recommended to use a file naming pattern which will allow for easily distinguishing between the current live snapshot, and any new snapshot which is being created.
A proper snapshot implementation will store the term, index and membership config as part of the snapshot, which should be decoded for creating this method's response data.