1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
.. _algorithm:
:c:struct:`raft` --- Algorithm state
====================================
The :c:struct:`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 :c:func:`raft_step()` function is used to advance the state of a
:c:struct:`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:
.. code-block:: C
/* 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 :c:func:`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.
.. _External events: ./events.html
.. _State updates: ./updates.html
Data types
----------
.. c:enum:: raft_state
Type code for the possible states a :c:struct:`raft` struct can be in.
.. code-block:: C
enum raft_state {
RAFT_FOLLOWER = 1,
RAFT_CANDIDATE,
RAFT_LEADER
};
.. c:struct:: raft
A single raft server in a cluster.
Public members
^^^^^^^^^^^^^^
.. c:member:: raft_id raft.id
Server ID. Readonly.
API
---
.. c:function:: int raft_init(struct raft *r, raft_id id, const char *address)
Initialize a raft state machine.
.. c:function:: int raft_close(struct raft* r)
Close a raft state machine, releasing all memory it uses.
.. c:function:: int raft_step(struct raft* r, struct raft_event *event, struct raft_update *update)
Advance the state of the given raft state machine.
.. c:function:: raft_term raft_current_term(const struct raft *r)
Return the current term of this server.
.. c:function:: 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.
.. c:function:: enum raft_state raft_state(struct raft *r)
Return the code of the current Raft state (follower/candidate/leader).
.. c:function:: raft_index raft_commit_index(const struct raft *r);
Return the commit index of this server.
.. c:function:: raft_time raft_timeout(const struct raft *r)
Return the time at which the next :c:macro:`RAFT_TIMEOUT` event should be
fired.
|
