{%- block navigation %}{{ navigation() }}{% endblock %}
{%- block localtoc %}{{ localtoc() }}{% endblock %}
{% block body %} {% endblock %}
struct raft_fsm — Application state machine¶The FSM struct defines the interface that the application’s state machine must implement in order to be replicated by Raft.
raft_fsm¶Hold pointers to an actual implementation of the FSM interface.
data¶Space for user-defined arbitrary data. C-Raft does not use and does not touch this field.
version¶API version implemented by this instance. Currently 1.
(*apply)(struct raft_fsm *fsm, const struct raft_buffer *buf, void **result)¶Apply a committed RAFT_COMMAND entry to the state machine.
C-Raft is a fully asynchronous C implementation of the Raft consensus protocol.
The library has modular design: its core part implements only the core Raft algorithm logic, in a fully platform independent way. On top of that, a pluggable interface defines the I/O implementation for networking and disk persistence.
A stock implementation of the I/O interface is provided when building the library with default options. It is based on libuv and should fit the vast majority of use cases.
C-Raft implements all the basic features described in the Raft dissertation:
Leader election
Log replication
Log compaction
Membership changes
It also includes a few optional enhancements:
Optimistic pipelining to reduce log replication latency
Writing to leader’s disk in parallel
Automatic stepping down when the leader loses quorum
Leadership transfer extension
Non-voting servers
Make sure that libuv is installed on your system, then run:
1 2 3 | autoreconf -i
./configure --enable-example
make
|
Then create a main.c file with this simple test program that just runs a
single raft server and implements a basic state machine for incrementing a
counter:
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 | #include <raft.h>
#include <raft/uv.h>
static raft_id id = 12345;
static const char *address = "127.0.0.1:8080";
static const char *dir = "/tmp/raft-quick-start";
static struct uv_loop_s loop;
static struct raft_uv_transport transport;
static struct raft_io io;
static struct raft_fsm fsm;
static struct raft raft;
static struct raft_configuration conf;
static struct uv_timer_s timer;
static struct raft_apply apply;
static unsigned counter = 0;
static uint64_t command;
static int applyCommand(struct raft_fsm *fsm,
const struct raft_buffer *buf,
void **result) {
counter += *(uint64_t *)buf->base;
printf("counter: %u\n", counter);
return 0;
}
static void submitCommand(uv_timer_t *timer) {
struct raft_buffer buf;
command = uv_now(timer->loop) % 10;
buf.len = sizeof command;
buf.base = &command;
raft_apply(&raft, &apply, &buf, 1, NULL);
}
int main() {
mkdir(dir, 0755);
uv_loop_init(&loop);
raft_uv_tcp_init(&transport, &loop);
raft_uv_init(&io, &loop, dir, &transport);
fsm.apply = applyCommand;
raft_init(&raft, &io, &fsm, id, address);
raft_configuration_init(&conf);
raft_configuration_add(&conf, id, address, RAFT_VOTER);
raft_bootstrap(&raft, &conf);
raft_start(&raft);
uv_timer_init(&loop, &timer);
uv_timer_start(&timer, submitCommand, 0, 1000);
uv_run(&loop, UV_RUN_DEFAULT);
}
|
You can compile and run it with:
1 | cc main.c -o main -lraft -luv && ./main
|
struct raft_io — I/O backend interface¶The I/O backend struct defines an interface for performing periodic ticks, log store read/write and send/receive of network RPCs.
raft_io¶Hold pointers to an actual implementation of the I/O backend interface.
(*raft_io_close_cb)(struct raft_io *io)¶Type definition for callback passed to raft_io.close().
(*raft_io_tick_cb)(struct raft_io *io)¶Callback invoked by the I/O implementation at regular intervals.
(*raft_io_recv_cb)(struct raft_io *io, struct raft_message *msg)¶Callback invoked by the I/O implementation when an RPC message is received.
data¶Space for user-defined arbitrary data. C-Raft does not use and does not touch this field.
version¶API version implemented by this instance. Currently 1.
impl¶Implementation-defined state.
char errmsg[RAFT_ERRMSG_BUF_SIZE]Human-readable message providing diagnostic information about the last error occurred.
(*init)(struct raft_io *io, raft_id id, const char *address)¶Initialize the backend with operational parameters such as server ID and address.
(*close)(struct raft_io *io, raft_io_close_cb cb)¶Release all resources used by the backend.
The tick and recv callbacks must not be invoked anymore, and
pending asynchronous requests be completed or canceled as soon as
possible. Invoke the close callback once the raft_io instance can
be freed.
(*load)(struct raft_io *io, raft_term *term, raft_id *voted_for, struct raft_snapshot **snapshot, raft_index *start_index, struct raft_entry *entries[], size_t *n_entries)¶Load persisted state from storage.
The implementation must synchronously load the current state from its storage backend and return information about it through the given pointers.
The implementation can safely assume that this method will be invoked exactly
one time, before any call to raft_io.append() or
c:func:raft_io.truncate(), and then won’t be invoked again.
The snapshot object and entries array must be allocated and populated using
raft_malloc(). If this function completes successfully, ownership of
such memory is transferred to the caller.
(*start)(struct raft_io *io, unsigned msecs, raft_io_tick_cb tick, raft_io_recv_cb recv)¶Start the backend.
From now on the implementation must start accepting RPC requests and must
invoke the tick callback every msecs milliseconds. The
recv callback must be invoked when receiving a message.
(*bootstrap)(struct raft_io *io, const struct raft_configuration *conf)¶Bootstrap a server belonging to a new cluster.
The implementation must synchronously persist the given configuration as the first entry of the log. The current persisted term must be set to 1 and the vote to nil.
If an attempt is made to bootstrap a server that has already some state, then RAFT_CANTBOOTSTRAP must be returned.
(*recover)(struct raft_io *io, const struct raft_configuration *conf)¶Force appending a new configuration as last entry of the log.
(*set_term)(struct raft_io *io, raft_term term)¶Synchronously persist current term (and nil vote).
The implementation MUST ensure that the change is durable before returning
(e.g. using fdatasync() or O_DSYNC).
(*set_vote)(struct raft_io *io, raft_id server_id)¶Synchronously persist who we voted for.
The implementation MUST ensure that the change is durable before returning
(e.g. using fdatasync() or O_DSYNC).
(*send)(struct raft_io *io, struct raft_io_send *req, const struct raft_message *message, raft_io_send_cb cb)¶Asynchronously send an RPC message.
The implementation is guaranteed that the memory referenced in the given
message will not be released until the cb callback is invoked.
(*append)(struct raft_io *io, struct raft_io_append *req, const struct raft_entry entries[], unsigned n, raft_io_append_cb cb)¶Asynchronously append the given entries to the log.
The implementation is guaranteed that the memory holding the given entries
will not be released until the cb callback is invoked.
(*truncate)(struct raft_io *io, raft_index index)¶Asynchronously truncate all log entries from the given index onwards.
(*snapshot_put)(struct raft_io *io, unsigned trailing, struct raft_io_snapshot_put *req, const struct raft_snapshot *snapshot, raft_io_snapshot_put_cb cb)¶Asynchronously persist a new snapshot. If the trailing parameter is
greater than zero, then all entries older that snapshot->index -
trailing must be deleted. If the trailing parameter is 0,
then the snapshot completely replaces all existing entries, which should all
be deleted. Subsequent calls to append() should append entries starting at
index snapshot->index + 1.
If a request is submitted, the raft engine won’t submit any other request until the original one has completed.
struct raft_io \u2014 I/O backend interface","struct raft \u2014 Raft server"],titleterms:{"public":[1,4,5],api:[0,5],applic:1,backend:4,data:[1,4,5],design:3,featur:3,get:2,interfac:4,licenc:3,machin:1,member:[1,4,5],quick:3,raft:[3,5],raft_fsm:1,raft_io:4,refer:0,server:5,start:[2,3],state:1,struct:[1,4,5],toc:3,type:[1,4,5]}}) raft-0.11.3/docs/build/server.html 0000664 0000000 0000000 00000022720 14156145273 0016766 0 ustar 00root root 0000000 0000000
struct raft — Raft server¶The raft server struct is the central part of C-Raft. It holds and drive the state of a single raft server in a cluster.
raft¶A single raft server in a cluster.
raft_id¶Hold the value of a raft server ID. Guaranteed to be at least 64-bit long.
(*raft_close_cb)(struct raft *r)¶Type definition for callback passed to raft_close().
raft_init(struct raft *r, struct raft_io *io, struct raft_fsm *fsm, raft_id id, const char *address)¶Initialize a raft server object.
raft_close(struct raft* r, raft_close_cb cb)¶Close a raft server object, releasing all used resources.
The memory of the object itself can be released only once the given close callback has been invoked.
raft_start(struct raft* r)¶Start a raft server.
The initial term, vote, snapshot and entries will be loaded from disk using
the raft_io->load() method. The instance will start as follower, unless
it’s the only voting server in the cluster, in which case it will
automatically elect itself and become leader.