# `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;