2 Getting started

The simplest Seastar program is this:

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

int main(int argc, char** argv) {
    seastar::app_template app;
    app.run(argc, argv, [] {
            std::cout << "Hello world\n";
            return seastar::make_ready_future<>();
    });
}

As we do in this example, each Seastar program must define and run, an app_template object. This object starts the main event loop (the Seastar engine) on one or more CPUs, and then runs the given function - in this case an unnamed function, a lambda - once.

The return make_ready_future<>(); causes the event loop, and the whole application, to exit immediately after printing the “Hello World” message. In a more typical Seastar application, we will want event loop to remain alive and process incoming packets (for example), until explicitly exited. Such applications will return a future which determines when to exit the application. We will introduce futures and how to use them below. In any case, the regular C exit() should not be used, because it prevents Seastar or the application from cleaning up appropriately.

As shown in this example, all Seastar functions and types live in the “seastar” namespace. An user can either type this namespace prefix every time, or use shortcuts like “using seastar::app_template” or even “using namespace seastar” to avoid typing this prefix. We generally recommend to use the namespace prefixes seastar and std explicitly, and will follow this style in all the examples below.

To compile this program (it’s present in the demos/hello-world.cc file) you can just use Docker.

$ docker build -t seastar-dev  -f ./docker/dev/Dockerfile .
$ scripts/build.sh dev
$ docker run -it --rm -v $(pwd):/seastar seastar-dev /seastar/build/dev/demos/hello-world_demo -c1

Without the docker help, first make sure you have downloaded, built, and optionally installed Seastar, and put the above program in a source file anywhere you want, let’s call the file getting-started.cc.

Linux’s pkg-config is one way for easily determining the compilation and linking parameters needed for using various libraries - such as Seastar. For example, if Seastar was built in the directory $SEASTAR but not installed, one can compile getting-started.cc with it using the command:

c++ getting-started.cc `pkg-config --cflags --libs --static $SEASTAR/build/release/seastar.pc`

The “--static” is needed because currently, Seastar is built as a static library, so we need to tell pkg-config to include its dependencies in the link command (whereas, had Seastar been a shared library, it could have pulled in its own dependencies).

If Seastar was installed, the pkg-config command line is even shorter:

c++ getting-started.cc `pkg-config --cflags --libs --static seastar`

Alternatively, one can easily build a Seastar program with CMake. Given the following CMakeLists.txt

cmake_minimum_required (VERSION 3.5)

project (SeastarExample)

find_package (Seastar REQUIRED)

add_executable (example
  getting-started.cc)

target_link_libraries (example
  PRIVATE Seastar::seastar)

you can compile the example with the following commands:

$ mkdir build
$ cd build
$ cmake ..
$ make

The program now runs as expected:

$ ./example
Hello world
$