SeaStar is an event-driven framework allowing you to write non-blocking, asynchronous code in a relatively straightforward manner (once understood). It is based on futures.
For more details and alternative work-flows, read HACKING.md.
Assuming that you would like to use system packages (RPMs or DEBs) for Seastar's dependencies, first install them:
$ sudo ./install-dependencies.shthen configure (in "release" mode):
$ ./configure.py --mode=releasethen compile:
$ ninja -C build/releaseIf you're missing a dependency of Seastar, then it is possible to have the configuration process fetch a version of the dependency locally for development.
For example, to fetch fmt locally, configure Seastar like this:
$ ./configure.py --mode=dev --cook fmt--cook can be repeated many times for selecting multiple dependencies.
The configure.py script is a wrapper around cmake. The --mode argument maps to CMAKE_BUILD_TYPE, and supports the following modes
| CMake mode | Debug info | Optimizations | Sanitizers | Allocator | Checks | Use for | |
|---|---|---|---|---|---|---|---|
| debug | Debug |
Yes | -O0 |
ASAN, UBSAN | System | All | gdb |
| release | RelWithDebInfo |
Yes | -O3 |
None | Seastar | Asserts | production |
| dev | Dev (Custom) |
No | -O1 |
None | Seastar | Asserts | build and test cycle |
| sanitize | Sanitize (Custom) |
Yes | -Os |
ASAN, UBSAN | System | All | second level of tests, track down bugs |
Note that seastar is more sensitive to allocators and optimizations than usual. A quick rule of the thumb of the relative performances is that release is 2 times faster than dev, 150 times faster than sanitize and 300 times faster than debug.
It's possible to consume Seastar directly from its build directory with CMake or pkg-config.
We'll assume that the Seastar repository is located in a directory at $seastar_dir.
Via pkg-config:
$ g++ my_app.cc $(pkg-config --libs --cflags --static $seastar_dir/build/release/seastar.pc) -o my_appand with CMake using the Seastar package:
CMakeLists.txt for my_app:
find_package (Seastar REQUIRED)
add_executable (my_app
my_app.cc)
target_link_libraries (my_app
Seastar::seastar)$ mkdir $my_app_dir/build
$ cd $my_app_dir/build
$ cmake -DCMAKE_PREFIX_PATH="$seastar_dir/build/release;$seastar_dir/build/release/_cooking/installed" -DCMAKE_MODULE_PATH=$seastar_dir/cmake $my_app_dirThe CMAKE_PREFIX_PATH values ensure that CMake can locate Seastar and its compiled submodules. The CMAKE_MODULE_PATH value ensures that CMake can uses Seastar's CMake scripts for locating its dependencies.
You can also consume Seastar after it has been installed to the file-system.
Important:
$build_dir/_cooking/installedFirst, configure the installation path:
$ ./configure.py --mode=release --prefix=/usr/localthen run the install target:
$ ninja -C build/release installthen consume it from pkg-config:
$ g++ my_app.cc $(pkg-config --libs --cflags --static seastar) -o my_appor consume it with the same CMakeLists.txt as before but with a simpler CMake invocation:
$ cmake ..(If Seastar has not been installed to a "standard" location like /usr or /usr/local, then you can invoke CMake with -DCMAKE_PREFIX_PATH=$my_install_root.)
There are also instructions for building on any host that supports Docker.
Seastar supports both C++17, and C++20. It can be selected with the
--c++-dialect=gnu++17 configure option or, if using CMake directly,
by setting on the Seastar_CXX_DIALECT CMake variable.
See the compatibity statement for more information.
There is a mini tutorial and a more comprehensive one.
The documentation is available on the web.
Ask questions and post patches on the development mailing list. Subscription information and archives are available here, or just send an email to seastar-dev@googlegroups.com.
Information can be found on the main project website.
File bug reports on the project issue tracker.
Seastar comes with its own userspace TCP/IP stack for better performance.