Seastar Framework Documentation

Seastar is a C++14 library designed for building highly efficient, complex server applications on modern multi-core machines. It addresses the limitations of traditional synchronous (process/thread-per-connection) and simple asynchronous (callback-heavy) models by providing a framework that handles both network and disk I/O with optimal performance.

Key architectural pillars include:

• Cooperative micro-task scheduler: Each core runs a lightweight scheduler that processes tasks (e.g., handling I/O results) without the overhead of OS context switching.
• Share-nothing SMP architecture: Each core (often called a shard) operates independently. Memory and data structures are not shared; instead, cores communicate via explicit message passing to avoid cache line bouncing and lock contention.
• Future-based APIs: Uses futures and continuations to represent and chain asynchronous events (network, disk, or inter-core communication) in a manageable way.
• High-performance stacks: Includes a share-nothing TCP/IP stack with zero-copy capabilities and DMA-based storage APIs for zero-copy disk I/O.

The Seastar IO scheduler uses a rate-limiter to throttle the amount of data dispatched to the disk. It prevents disk saturation by modeling disk behavior using a combination of bandwidth and IOPS (Input/Output Operations Per Second) for both reads and writes.

Core Concepts

• Tickets: Every IO request is assigned a 2D value called a "ticket".
  • Reads: Assigned a value of (1, bytes).
  • Writes: Assigned a value of (m_o, m_b * bytes), where m_o and m_b are normalization constants derived from the maximum possible IOPS and bandwidth for reads and writes.
• Normalization: The scheduler converts these tickets into a single cost using the formula: N(ticket) = (ticket_0 / iops_r_max) + (ticket_1 / bandwidth_r_max)
• Token Bucket: The time-derivative limitation is implemented via a token bucket algorithm. The bucket has a refill rate of 1.0. Each request consumes a fractional token value equal to its normalized cost N(ticket).
• Latency Goal: The maximum capacity of the token bucket (limit) is calculated based on the io_latency_goal_ parameter, representing the amount of tokens that can accumulate during that target duration.

If you are using an external semaphore to limit total parallelism across multiple different loops, you cannot use that semaphore to wait for a specific loop's completion (as limit.wait(N) would wait for all loops to finish).

Instead, use a seastar::gate to track the lifecycle of operations within a specific loop. Use gate.enter() when starting an operation and gate.leave() in a .finally() block when the operation completes. Finally, call gate.close() to wait for all operations associated with that gate to finish.

thread_local seastar::semaphore limit(100);
seastar::future<> f() {
    return seastar::do_with(seastar::gate(), [] (auto& gate) {
        return seastar::do_for_each(boost::counting_iterator<int>(0),
                boost::counting_iterator<int>(456), [&gate] (int i) {
            return seastar::get_units(limit, 1).then([&gate] (auto units) {
                gate.enter();
                seastar::futurize_invoke(slow).finally([&gate, units = std::move(units)] {
                    gate.leave();
                });
            });
        }).finally([&gate] {
            return gate.close();
        });
    });
}

The preferred way to write efficient asynchronous code in Seastar is using C++20 coroutines. A coroutine is a function that returns a seastar::future<T> and utilizes the co_await or co_return keywords. Coroutines integrate seamlessly with traditional Seastar code; they can be called from non-coroutine functions and can call non-coroutine functions.

Requirements:

• C++20 support.
• A compatible compiler (Clang 10+ is known to work).

When using co_await on a seastar::future, if the future is not ready, the coroutine suspends, allowing Seastar to perform other work. Once the future is ready, the coroutine resumes, and the value is extracted.

#include <seastar/core/coroutine.hh>

seastar::future<int> read();
seastar::future<> write(int n);

seastar::future<int> slow_fetch_and_increment() {
    auto n = co_await read();     // #1
    co_await seastar::sleep(1s);  // #2
    auto new_n = n + 1;           // #3
    co_await write(new_n);        // #4
    co_return n;                  // #5
}

Seastar applications should use seastar::app_template to manage command-line arguments. This allows you to integrate your custom options with Seastar's standard options (like -c for threads and -m for memory) using boost::program_options.

To add options:

1. Instantiate seastar::app_template.
2. Use app.add_options() to define flags and valued options.
3. Use app.add_positional_options() for arguments that don't start with a dash.
4. Call app.run(argc, argv, callback) to start the application. Inside the callback, retrieve settings via app.configuration().

#include <seastar/core/app-template.hh>
#include <seastar/core/reactor.hh>

int main(int argc, char** argv) {
    seastar::app_template app;
    namespace bpo = boost::program_options;
    app.add_options()
        ("flag", "some optional flag")
        ("size,s", bpo::value<int>()->default_value(100), "size")
        ;
    app.add_positional_options({
       { "filename", bpo::value<std::vector<seastar::sstring>>()->default_value({}),
         "sstable files to verify", -1}
    });
    app.run(argc, argv, [&app] {
        auto& args = app.configuration();
        if (args.count("flag")) {
            std::cout << "Flag is on\n";
        }
        std::cout << "Size is " << args["size"].as<int>() << "\n";
        return seastar::make_ready_future<>();
    });
    return 0;
}

Seastar provides two generator variants. Choosing the correct one is critical for performance based on your data type and latency requirements.

Unbuffered Generator

Best for:

• Large objects where moves are expensive.
• Latency-critical applications (need the first element immediately).
• Memory-constrained environments.
• Elements that are naturally references to existing data.

Characteristics:

• Zero-copy: Stores a pointer to the value in the producer's stack frame.
• One suspension per element.

Buffered Generator

Best for:

• Throughput-oriented applications.
• Small, cheap-to-move elements (integers, small PODs).
• Scenarios where the producer can generate elements in batches.

CRITICAL PERFORMANCE NOTE: When using a buffered generator, you must use a fixed-capacity container like circular_buffer_fixed_capacity to avoid heap allocations. Using std::vector can make the generator up to 2.6x slower and increase allocations due to dynamic memory overhead.

Characteristics:

• Amortized suspensions (multiple elements per suspension).
• Moves elements into a buffer for independent lifetime.