raft — Algorithm state

The raft struct is the central part of C-Raft. It holds and drive the state of a single Raft server in a cluster.

It is purely a finite state machine, and it doesn’t perform any I/O or system calls.

The raft_step() function is used to advance the state of a raft state machine, and is designed to be integrated in some external event loop or I/O layer that is in charge of receiving users requests, implementing network communication with other Raft servers, persisting data to disk.

For example:

/* A RequestVote RPC message has been received from the network. We inform
 * struct raft about that by passing a struct raft_event to raft_step(). */
struct raft raft;
struct raft_event event;
struct raft_update update;

event.type = RAFT_RECEIVE;
event.receive.message = ...; /* Fill with the content of the message */

raft_step(&raft, &event, &update);

/* The struct raft_update object contains information about the next actions
 * the I/O layer should perform, for example it might contain new messages to
 * be sent. */
if (update.flags & RAFT_UPDATE_MESSAGES) {
    for (unsigned i = 0; i < update.messages.n; i++) {
        /* Send the message contained in update.messages.batch[i] */
    }
}

Basically whenever an event occurs in the I/O layer, the raft_step() function must be called and the resulting state updates should be performed.

See the External events section for details about what events to pass to the step function in order to drive the state machine forward, and State updates for details about how state updates should be processed after calling the step function.

Data types

enum raft_state

Type code for the possible states a raft struct can be in.

enum raft_state {
    RAFT_FOLLOWER = 1,
    RAFT_CANDIDATE,
    RAFT_LEADER
};

struct raft

A single raft server in a cluster.

Public members

raft_id raft.id

Server ID. Readonly.

API

int raft_init(struct raft *r, raft_id id, const char *address)

Initialize a raft state machine.

int raft_close(struct raft *r)

Close a raft state machine, releasing all memory it uses.

int raft_step(struct raft *r, struct raft_event *event, struct raft_update *update)

Advance the state of the given raft state machine.

raft_term raft_current_term(const struct raft *r)

Return the current term of this server.

raft_id raft_voted_for(const struct raft *r)

Return the ID of the server that this server has voted for, or :c:expr:0 if it did not vote.

enum raft_state raft_state(struct raft *r)

Return the code of the current Raft state (follower/candidate/leader).

raft_index raft_commit_index(const struct raft *r);

Return the commit index of this server.

raft_time raft_timeout(const struct raft *r)

Return the time at which the next RAFT_TIMEOUT event should be fired.