Struct simple_raft::node::RaftNode

pub struct RaftNode<Log, Random, NodeId> { /* fields omitted */ }

A Raft node, used for replicating a strongly-consistent distributed log of entries with arbitrary data amongst its peers.

The distributed log can be used, for example, to replicate transactions in a database.

Appending entries to the distributed log

Log entries passed to append are not guaranteed to ultimately be appended to the distributed log, and may be cancelled any time receive is called before they are “committed”. The provided RaftLog should provide an API to find out which log entries have been cancelled. Only log entries passed to append on a particular node are guaranteed to appear as cancelled in its own RaftLog, but entries appended on other nodes may appear as well.

The distributed log may only be appended to by the node returned by leader, but even that node is not guaranteed to be able to append to the log, since it must be able to send each new entry to a majority of its peers before losing leadership in order for the entry to become committed. The leader may change at any time, and therefore an entry may be first returned from take_committed on a node different than that to which it was submitted. However, take_committed is guaranteed to return the same entries in the same order on every node.

Timer ticks

Timeouts in RaftNode are driven by a timer ticking at fixed interval, with the number of ticks between timeouts configured by the provided RaftConfig. Any consistent time interval between ticks may be chosen, but the time interval and RaftConfig must be the same on all peers in a group. Shorter timeouts will allow Raft to react quicker to network disruptions, but may result in spurious leadership changes when the network latency exceeds time_interval * election_timeout_ticks.

Message delivery

Unicast message delivery is assumed to be non-lossy in order for replication to make progress. In other words, once a non-broadcast SendableRaftMessage is returned from an API such as append, receive, or timer_tick, it must be retained and retransmitted until it is confirmed to have been processed by receive on its destination. Messages may be safely delivered out-of-order or more than once, however.

To prevent unbounded queueing, the API is designed to only ever return a bounded amount of unacknowledged unicast message data. This amount can be approximately controlled by replication_chunk_size.

Implementations

impl<Log, Random, NodeId> RaftNode<Log, Random, NodeId> where
    Log: RaftLog,
    Random: RngCore,
    NodeId: Ord + Clone + Display, 

pub fn new(
    node_id: NodeId,
    peers: BTreeSet<NodeId>,
    log: Log,
    random: Random,
    config: RaftConfig
) -> Self

Constructs a new Raft node with specified peers and configuration.

The Raft node will start with an empty initial state. The log provided should also be in an empty initial state. Each Raft node in a group must be constructed with the same set of peers and config. peers may contain node_id or omit it to the same effect. rand must produce different values on every node in a group.

pub fn append<T: Into<Bytes>>(
    &mut self,
    data: T
) -> Result<impl Iterator<Item = SendableRaftMessage<NodeId>> + '_, AppendError<Log::Error>>

Request appending an entry with arbitrary data to the Raft log, returning messages to be sent.

See “Message delivery” for details about delivery requirements for the returned messages.

Errors

If this request would immediately be cancelled, then an error is returned.

pub fn config(&self) -> &RaftConfig

Returns this node’s configurable parameters.

pub fn is_leader(&self) -> bool

Returns whether this node is the leader of the latest known term.

pub fn last_committed_log_index(&self) -> LogIndex

Returns the index of the last LogEntry which has been committed and thus may be returned by take_committed.

pub fn leader(&self) -> (Option<&NodeId>, TermId)

Returns the ID of the leader, if there is one, of the latest known term, along with the term.

pub fn log(&self) -> &Log

Returns a reference to the Raft log storage.

pub fn log_mut(&mut self) -> &mut Log

Returns a mutable reference to the Raft log storage.

pub fn node_id(&self) -> &NodeId

Returns this node’s ID.

pub fn peers(&self) -> &BTreeSet<NodeId>

Returns the IDs of this node’s peers.

pub fn receive(
    &mut self,
    message: RaftMessage,
    from: NodeId
) -> impl Iterator<Item = SendableRaftMessage<NodeId>> + '_

Processes receipt of a message from a peer with ID from, returning messages to be sent.

See “Message delivery” for details about delivery requirements for the returned messages.

pub fn replication_state(
    &self,
    peer_node_id: &NodeId
) -> Option<&ReplicationState>

Returns the replication state corresponding to the peer with ID peer_node_id.

pub fn state(&mut self) -> &RaftState<Log, Random, NodeId>

Returns a reference to the low-level state of the Raft node.

pub fn state_mut(&mut self) -> &mut RaftState<Log, Random, NodeId>

Returns a mutable reference to the low-level state of the Raft node.

pub fn take_committed(&mut self) -> CommittedIter<'_, Log>

Returns an iterator yielding committed log entries. A given LogEntry will be yielded only once over the lifetime of a RaftNode. See “Appending entries to the distributed log” for details about log commital.

pub fn timer_tick(
    &mut self
) -> impl Iterator<Item = SendableRaftMessage<NodeId>> + '_

Ticks forward this node’s internal clock by one tick, returning messages to be sent.

See “Message delivery” for details about delivery requirements for the returned messages.