raft_event — External events

Information about new events that should be passed to raft_step(),

Data types

enum raft_event_type

Event type codes.

enum raft_event_type {
    RAFT_START = 1,          /* Initial event starting loading persisted data */
    RAFT_RECEIVE,            /* A message has been received from another server */
    RAFT_PERSISTED_ENTRIES,  /* Some entries have been persisted to disk */
    RAFT_PERSISTED_SNAPSHOT, /* A snapshot has been persisted */
    RAFT_CONFIGURATION,      /* A new committed configuration must be applied */
    RAFT_SNAPSHOT,           /* A snapshot has been taken */
    RAFT_TIMEOUT,            /* The timeout has expired */
    RAFT_SUBMIT,             /* New entries have been submitted */
    RAFT_CATCH_UP,           /* Start catching-up a server */
    RAFT_TRANSFER            /* Start transferring leadership to another server */
};

struct raft_event

The raft_event struct holds information about events such as:

• a new message has been received from another server

• disk I/O has been completed for persisting data

• new entries have been submitted for replication

Users of the core raft struct are responsible for implementing an I/O layer that watches for the above events, filling raft_event objects as appropriate and passing them to the raft_step() function.

Each raft_event_type has an associated sub-struct, whose fields are described separately in the sections below.

struct raft_event
{
    raft_time time;            /* Must be filled with the current time */
    enum raft_event_type type; /* Must be filled with the type code of the event */
    unsigned char unused;
    unsigned short capacity;   /* Disk capacity that has been reserved */
    unsigned char reserved[4];
    union {                    /* Additional data about a specific event type */
        struct { ... } start;
        struct { ... } receive;
        struct { ... } persisted_entries;
        struct { ... } persisted_snapshot;
        struct { ... } configuration;
        struct { ... } snapshot;
        struct { ... } submit;
        struct { ... } catch_up;
        struct { ... } transfer;
    };
};

Common fields

raft_time raft_event.time

Event timestamp. Must always be filled with the current time.

enum raft_event_type raft_event.type

Event type. Must be filled with the type code of the event.

unsigned short raft_event.capacity

Disk capacity that has been reserved and is guaranteed to be available.

Start

struct [anonymous] raft_event.start

To be filled when raft_event.type is RAFT_START.

It contains all state persisted on disk by the server.

struct
{
     raft_term term;                          /* Current term */
     raft_id voted_for;                       /* Current vote */
     struct raft_snapshot_metadata *metadata; /* Last snapshot, if any */
     raft_index start_index;                  /* Index of first entry */
     struct raft_entry *entries;              /* Array of persisted entries */
     unsigned n_entries;                      /* Length of entries array */
} start;

Receive

struct [anonymous] raft_event.receive

To be filled when raft_event.type is RAFT_RECEIVE.

It contains the raft_message being received.

struct
{
    struct raft_message *message; /* Message being received */
} receive;

Persisted entries

struct [anonymous] raft_event.persisted_entries

To be filled when raft_event.type is RAFT_PERSISTED_ENTRIES.

It contains the latest log index that has been successfully persisted.

struct
{
    raft_index index; /* Highest index persisted */
} persisted_entries;

Persisted snapshot

struct [anonymous] raft_event.persisted_snapshot

To be filled when raft_event.type is RAFT_PERSISTED_SNAPSHOT.

It contains metadata about the latest snapshot that has been successfully persisted.

struct
{
    struct raft_snapshot_metadata metadata;
    size_t offset;
    bool last;
} persisted_snapshot;

Configuration

struct [anonymous] raft_event.configuration

To be filled when raft_event.type is RAFT_CONFIGURATION.

It contains the last committed configuration that has been processed.

struct
{
    raft_index index;
    struct raft_configuration conf;
} configuration;

Snapshot taken

struct [anonymous] raft_event.snapshot

To be filled when raft_event.type is RAFT_SNAPSHOT.

It contains metadata about the last snapshot that has been taken.

struct
{
    struct raft_snapshot_metadata metadata; /* Snapshot metadata */
    unsigned trailing;                      /* Trailing entries kept */
} snapshot;

Submit

struct [anonymous] raft_event.submit

To be filled when raft_event.type is RAFT_SUBMIT.

It contains new entries that have been submitted for replication.

struct
{
    struct raft_entry *entries;
    unsigned n;
} submit;

Catch-up server

struct [anonymous] raft_event.catch_up

To be filled when raft_event.type is RAFT_CATCH_UP.

It contains the ID of a server that should be caught-up with the leader log.

struct
{
    raft_id server_id;
} catch_up;

Transfer leadership

struct [anonymous] raft_event.transfer

To be filled when raft_event.type is RAFT_TRANSFER.

It contains the ID of a server that leadership should be transfered to.

struct
{
    raft_id server_id;
} transfer;