Struct raft::Raft

pub struct Raft<T: Storage> {
    pub term: u64,
    pub vote: u64,
    pub id: u64,
    pub read_states: Vec<ReadState>,
    pub raft_log: RaftLog<T>,
    pub max_inflight: usize,
    pub max_msg_size: u64,
    pub pending_request_snapshot: u64,
    pub state: StateRole,
    pub is_learner: bool,
    pub votes: HashMap<u64, bool>,
    pub msgs: Vec<Message>,
    pub leader_id: u64,
    pub lead_transferee: Option<u64>,
    pub pending_conf_index: u64,
    pub read_only: ReadOnly,
    pub election_elapsed: usize,
    pub check_quorum: bool,
    pub pre_vote: bool,
    // some fields omitted
}

A struct that represents the raft consensus itself. Stores details concerning the current and possible state the system can take.

Fields

term: u64

The current election term.

vote: u64

Which peer this raft is voting for.

id: u64

The ID of this node.

read_states: Vec<ReadState>

The current read states.

raft_log: RaftLog<T>

The persistent log.

max_inflight: usize

The maximum number of messages that can be inflight.

max_msg_size: u64

The maximum length (in bytes) of all the entries.

pending_request_snapshot: u64

The peer is requesting snapshot, it is the index that the follower needs it to be included in a snapshot.

state: StateRole

The current role of this node.

is_learner: bool

Whether this is a learner node.

Learners are not permitted to vote in elections, and are not counted for commit quorums. They do replicate data from the leader.

votes: HashMap<u64, bool>

The current votes for this node in an election.

Reset when changing role.

msgs: Vec<Message>

The list of messages.

leader_id: u64

The leader id

lead_transferee: Option<u64>

ID of the leader transfer target when its value is not None.

If this is Some(id), we follow the procedure defined in raft thesis 3.10.

pending_conf_index: u64

Only one conf change may be pending (in the log, but not yet applied) at a time. This is enforced via pending_conf_index, which is set to a value >= the log index of the latest pending configuration change (if any). Config changes are only allowed to be proposed if the leader's applied index is greater than this value.

This value is conservatively set in cases where there may be a configuration change pending, but scanning the log is possibly expensive. This implies that the index stated here may not necessarily be a config change entry, and it may not be a BeginMembershipChange entry, even if we set this to one.

read_only: ReadOnly

The queue of read-only requests.

election_elapsed: usize

Ticks since it reached last electionTimeout when it is leader or candidate. Number of ticks since it reached last electionTimeout or received a valid message from current leader when it is a follower.

check_quorum: bool

Whether to check the quorum

pre_vote: bool

Enable the prevote algorithm.

This enables a pre-election vote round on Candidates prior to disrupting the cluster.

Enable this if greater cluster stability is preferred over faster elections.

Methods

impl<T: Storage> Raft<T>

pub fn pending_membership_change(&self) -> &Option<ConfChange>

The last BeginMembershipChange entry. Once we make this change we exit the joint state.

This is different than pending_conf_index since it is more specific, and also exact. While pending_conf_index is conservatively set at times to ensure safety in the one-by-one change method, in joint consensus based changes we track the state exactly. The index here must only be set when a BeginMembershipChange is present at that index.

Caveats

It is important that whenever this is set that pending_conf_index is also set to the value if it is greater than the existing value.

Use Raft::set_pending_membership_change() to change this value.

impl<T: Storage> Raft<T>

pub fn new(c: &Config, store: T) -> Result<Raft<T>>

Creates a new raft for use on the node.

pub fn with_logger(self, logger: &Logger) -> Self

Set a logger.

pub fn get_store(&self) -> &T

Grabs an immutable reference to the store.

pub fn mut_store(&mut self) -> &mut T

Grabs a mutable reference to the store.

pub fn get_snap(&self) -> Option<&Snapshot>

Grabs a reference to the snapshot

pub fn pending_read_count(&self) -> usize

Returns the number of pending read-only messages.

pub fn ready_read_count(&self) -> usize

Returns how many read states exist.

pub fn soft_state(&self) -> SoftState

Returns a value representing the softstate at the time of calling.

pub fn hard_state(&self) -> HardState

Returns a value representing the hardstate at the time of calling.

pub fn in_lease(&self) -> bool

Returns whether the current raft is in lease.

pub fn get_election_timeout(&self) -> usize

Fetch the length of the election timeout.

pub fn get_heartbeat_timeout(&self) -> usize

Fetch the length of the heartbeat timeout

pub fn get_heartbeat_elapsed(&self) -> usize

Fetch the number of ticks elapsed since last heartbeat.

pub fn get_randomized_election_timeout(&self) -> usize

Return the length of the current randomized election timeout.

pub fn skip_bcast_commit(&mut self, skip: bool)

Set whether skip broadcast empty commit messages at runtime.

pub fn began_membership_change_at(&self) -> Option<u64>

Get the index which the pending membership change started at.

Note: This is an experimental feature.

pub fn set_batch_append(&mut self, batch_append: bool)

Set whether batch append msg at runtime.

pub fn send_append(&mut self, to: u64, pr: &mut Progress)

Sends RPC, with entries to the given peer.

pub fn bcast_append(&mut self)

Sends RPC, with entries to all peers that are not up-to-date according to the progress recorded in r.prs().

pub fn ping(&mut self)

Broadcasts heartbeats to all the followers if it's leader.

pub fn bcast_heartbeat(&mut self)

Sends RPC, without entries to all the peers.

pub fn maybe_commit(&mut self) -> bool

Attempts to advance the commit index. Returns true if the commit index changed (in which case the caller should call r.bcast_append).

pub fn commit_apply(&mut self, applied: u64)

Commit that the Raft peer has applied up to the given index.

Registers the new applied index to the Raft log.

Hooks

• Post: Checks to see if it's time to finalize a Joint Consensus state.

pub fn reset(&mut self, term: u64)

Resets the current node to a given term.

pub fn append_entry(&mut self, es: &mut [Entry])

Appends a slice of entries to the log. The entries are updated to match the current index and term.

pub fn tick(&mut self) -> bool

Returns true to indicate that there will probably be some readiness need to be handled.

pub fn tick_election(&mut self) -> bool

Run by followers and candidates after self.election_timeout.

Returns true to indicate that there will probably be some readiness need to be handled.

pub fn become_follower(&mut self, term: u64, leader_id: u64)

Converts this node to a follower.

pub fn become_candidate(&mut self)

Converts this node to a candidate

Panics

Panics if a leader already exists.

pub fn become_pre_candidate(&mut self)

Converts this node to a pre-candidate

Panics

Panics if a leader already exists.

pub fn become_leader(&mut self)

Makes this raft the leader.

Panics

Panics if this is a follower node.

pub fn campaign(&mut self, campaign_type: &[u8])

Campaign to attempt to become a leader.

If prevote is enabled, this is handled as well.

pub fn step(&mut self, m: Message) -> Result<()>

Steps the raft along via a message. This should be called everytime your raft receives a message from a peer.

pub fn begin_membership_change(
    &mut self,
    conf_change: &ConfChange
) -> Result<()>

Apply a BeginMembershipChange variant ConfChange.

Note: This is an experimental feature.

When a Raft node applies this variant of a configuration change it will adopt a joint configuration state until the membership change is finalized.

During this time the Raft will have two, possibly overlapping, cooperating quorums for both elections and log replication.

Errors

• ConfChange.change_type is not BeginMembershipChange
• ConfChange.configuration does not exist.
• ConfChange.start_index does not exist. It must equal the index of the corresponding entry.

pub fn finalize_membership_change(
    &mut self,
    conf_change: &ConfChange
) -> Result<()>

Apply a FinalizeMembershipChange variant ConfChange.

Note: This is an experimental feature.

When a Raft node applies this variant of a configuration change it will finalize the transition begun by [begin_membership_change].

Once this is called the Raft will no longer have two, possibly overlapping, cooperating qourums.

Errors

• This Raft is not in a configuration change via begin_membership_change.
• ConfChange.change_type is not a FinalizeMembershipChange.
• ConfChange.configuration value should not exist.
• ConfChange.start_index value should not exist.

pub fn request_snapshot(&mut self, request_index: u64) -> Result<()>

Request a snapshot from a leader.

pub fn handle_append_entries(&mut self, m: &Message)

For a given message, append the entries to the log.

pub fn handle_heartbeat(&mut self, m: Message)

For a message, commit and send out heartbeat.

pub fn restore(&mut self, snap: Snapshot) -> bool

Recovers the state machine from a snapshot. It restores the log and the configuration of state machine.

pub fn has_pending_conf(&self) -> bool

Check if there is any pending confchange.

This method can be false positive.

pub fn should_bcast_commit(&self) -> bool

Specifies if the commit should be broadcast.

pub fn promotable(&self) -> bool

Indicates whether state machine can be promoted to leader, which is true when its own id is in progress list.

pub fn propose_membership_change(
    &mut self,
    config: impl Into<Configuration>
) -> Result<()>

Propose that the peer group change its active set to a new set.

Note: This is an experimental feature.

use raft::{Raft, Config, storage::MemStorage, eraftpb::ConfState};
use raft::raw_node::RawNode;
let config = Config {
    id: 1,
    ..Default::default()
};
let store = MemStorage::new_with_conf_state((vec![1], vec![]));
let mut node = RawNode::new(&config, store).unwrap();
let mut raft = node.raft;
raft.become_candidate();
raft.become_leader(); // It must be a leader!

let mut conf = ConfState::default();
conf.nodes = vec![1,2,3];
conf.learners = vec![4];
if let Err(e) = raft.propose_membership_change(conf) {
    panic!("{}", e);
}

Errors

• This Peer is not leader.
• voters and learners are not mutually exclusive.
• voters is empty.

pub fn add_node(&mut self, id: u64) -> Result<()>

Adds a new node to the cluster.

Errors

• id is already a voter.
• id is already a learner.
• There is a pending membership change. (See is_in_membership_change())

pub fn add_learner(&mut self, id: u64) -> Result<()>

Adds a learner node.

Errors

• id is already a voter.
• id is already a learner.
• There is a pending membership change. (See is_in_membership_change())

pub fn remove_node(&mut self, id: u64) -> Result<()>

Removes a node from the raft.

Errors

• id is not a voter or learner.
• There is a pending membership change. (See is_in_membership_change())

pub fn set_progress(
    &mut self,
    id: u64,
    matched: u64,
    next_idx: u64,
    is_learner: bool
)

Updates the progress of the learner or voter.

pub fn take_prs(&mut self) -> ProgressSet

Takes the progress set (destructively turns to None).

pub fn set_prs(&mut self, prs: ProgressSet)

Sets the progress set.

pub fn prs(&self) -> &ProgressSet

Returns a read-only reference to the progress set.

pub fn mut_prs(&mut self) -> &mut ProgressSet

Returns a mutable reference to the progress set.

pub fn load_state(&mut self, hs: &HardState)

For a given hardstate, load the state into self.

pub fn pass_election_timeout(&self) -> bool

pass_election_timeout returns true iff election_elapsed is greater than or equal to the randomized election timeout in [election_timeout, 2 * election_timeout - 1].

pub fn reset_randomized_election_timeout(&mut self)

Regenerates and stores the election timeout.

pub fn send_timeout_now(&mut self, to: u64)

Issues a message to timeout immediately.

pub fn abort_leader_transfer(&mut self)

Stops the tranfer of a leader.

pub fn is_in_membership_change(&self) -> bool

Determine if the Raft is in a transition state under Joint Consensus.