Skip to content
C implementation of the Raft consensus protocol
C M4 C++ Other
Branch: master
Clone or download
Latest commit 25805d9 Nov 5, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ac Initial implementation Oct 30, 2018
benchmark Loop through all engines by default Oct 24, 2019
example Fix variadic macro empty args warnings Sep 18, 2019
include Add raft_io->recover() declaration Oct 31, 2019
m4 Initial implementation Oct 30, 2018
src set some safe default for possible non-exhaustive pattern-matching Nov 5, 2019
test uv: use properly unusual names within the macros Nov 5, 2019
.clang-format Fix warnings in test/unit/core Sep 19, 2019
.dir-locals.el
.gitignore Add OS disk benchmark program Oct 24, 2019
.travis.yml Rename RAFT_TEST to RAFT_TMP Sep 24, 2019
AUTHORS Initial implementation Oct 30, 2018
LICENSE Switch license LGPLv3 plus static linking exception Oct 24, 2019
Makefile.am Add initial raft_recover implementation and test Oct 31, 2019
README.md Add note in README about license. Oct 24, 2019
acinclude.m4 Improve uvProbeIoCapabilities tests Aug 6, 2019
configure.ac bump the version number Nov 5, 2019
raft.pc.in Initial implementation Oct 30, 2018

README.md

Build Status codecov

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 (send/receive RPC messages) and disk persistence (store log entries and snapshots).

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. The only catch is that it currently requires Linux, since it uses the Linux AIO API for disk I/O. Patches are welcome to add support for more platforms.

See raft.h for full documentation.

Licence

This raft C library is released under a slightly modified version of LGPLv3, that includes a copiright exception letting users to statically link the library code in their project and release the final work under their own terms. See the full license text.

Features

This implementation includes 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

Building

autoreconf -i
./configure --enable-example
make

Example

The best way to understand how to use the library is probably reading the code of the example server included in the source code.

You can also see the example server in action by running:

./example/cluster

which spawns a little cluster of 3 servers, runs a sample workload, and randomly stops and restarts a server from time to time.

Quick guide

It is recommended that you read raft.h for documentation details, but here's a quick high-level guide of what you'll need to do (error handling is omitted for brevity).

Create an instance of the stock raft_io interface implementation (or implement your own one if the one that comes with the library really does not fit):

const char *dir = "/your/raft/data";
struct uv_loop_s loop;
struct raft_uv_transport transport;
struct raft_io io;
uv_loop_init(&loop);
raft_uv_tcp_init(&transport, &loop);
raft_uv_init(&io, &loop, dir, &transport);

Define your application Raft FSM, implementing the raft_fsm interface:

struct raft_fsm
{
  void *data;
  int (*apply)(struct raft_fsm *fsm, const struct raft_buffer *buf, void **result);
  int (*snapshot)(struct raft_fsm *fsm, struct raft_buffer *bufs[], unsigned *n_bufs);
  int (*restore)(struct raft_fsm *fsm, struct raft_buffer *buf);
}

Create an instance of the stock raft_logger interface implementation:

struct raft_logger logger;
raft_stream_logger_init (&logger, stdout);

or

struct raft_logger logger;
raft_ring_logger_init (&logger, buffer_size);

Pick a unique ID and address for each server and initialize the raft object:

unsigned id = 1;
const char *address = "192.168.1.1:9999";
struct raft raft;
raft_init(&raft, &io, &fsm, &logger, id, address);

If it's the first time you start the cluster, create a configuration object containing each server that should be present in the cluster (typically just one, since you can grow your cluster at a later point using raft_add and raft_promote) and bootstrap:

struct raft_configuration configuration;
raft_configuration_init(&configuration);
raft_configuration_add(&configuration, 1, "192.168.1.1:9999", true);
raft_bootstrap(&raft, &configuration);

Start the raft server:

raft_start(&raft);
uv_run(&loop, UV_RUN_DEFAULT);

Asynchronously submit requests to apply new commands to your application FSM:

static void applyCb(struct raft_apply *req, int status, void *result) {
  /* ... */
}

struct raft_apply req;
struct raft_buffer buf;
buf.len = ...; /* The length of your FSM entry data */
buf.base = ...; /* Your FSM entry data */
raft_apply(&raft, &req, &buf, 1, apply_callback);

To add more servers to the cluster use the raft_add() and raft_promote APIs.

Notable users

Credits

Of course the biggest thanks goes to Diego Ongaro :) (the original author of the Raft dissertation)

A lot of ideas and inspiration was taken from other Raft implementations such as:

You can’t perform that action at this time.