Rseq is a userspace take on the proposed kernel restartable sequences API, and provides and mechanism to perform efficient per-cpu operations.

This isn't intended to be a long-running project. Instead, its goal is to allow userland experiments with rseq (without having to recompile the kernel), to collect data as to how useful it would be.

Here is a simple demonstration of how to use rseq and why it might be useful. A more thorough explanation (together with history and some implementation notes) can be found in Rseq.md.

rseq::Value<int> counterByCpu[kNumCpus];
void bumpCounter() {
  while (true) {
    int cpu = rseq::begin();
    // A plain atomic load. rseq::Value types are API-compatible with
    // std::atomic.
    int curValue = counterByCpu[cpu].load();
    // rseq::store takes no action and returns false if another thread might
    // have run on the same CPU after the call to rseq::begin(). Otherwise, the
    // store happens and the call returns true.
    bool success = rseq::store(&counterByCpu[cpu], curValue + 1);
    if (success) {
      break;
    }
  }
}

Rseq only works on Linux and x86-64. Building requires CMake and a recent version of clang or g++. Building the tests requires a gtest installation.

In this directory, run:

mkdir build
cd build
# Include the former option to produce an optimized build, and the latter to
# enable running tests.
cmake [-DCMAKE_BUILD_TYPE=Release] [-Dtest=ON] [-DCMAKE_INSTALL_PREFIX=</path/to/install/dir>] ../
make

# Now we can take some of our binaries for a test drive

# If you passed -Dtest=ON above, this will run all tests.
make test
# Run a benchmark of a variety of mechanisms for incrementing a set of
# counters.
./rseq_benchmark all 8 10000000

For the common case, you probably want:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
sudo make install

You can then compile programs that #include "rseq/Rseq.h" with g++ myProgram.cpp -lrseq.

See Rseq.md for a more thorough description. Essentially, each thread gets its own copy of the code that does an rseq operation. When one thread wants to evict another from ownership of a CPU, it patches that thread's copy of the function to jump to a failure path instead of doing the operation.

Rseq.md contains a more thorough description. Reading the comments in rseq/Rseq.h should give a working understanding of the API.

Rseq is BSD-licensed. We also provide an additional patent grant.