Repository files navigation

SeaStar is an event-driven framework allowing you to write non-blocking,asynchronous code in a relatively straightforward manner (once understood).It is based onfutures.

For more details and alternative work-flows, readHACKING.md.

Assuming that you would like to use system packages (RPMs or DEBs) for Seastar's dependencies, first install them:

$ sudo ./install-dependencies.sh

then configure (in "release" mode):

$ ./configure.py --mode=release

then compile:

$ ninja -C build/release

In case there are compilation issues, especially likeg++: internal compiler error: Killed (program cc1plus)try giving more memory to gcc, either by limiting the amount of threads ( -j1 ) and/or allowing at least 4g ram to yourmachine.

If 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 fetchfmt 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 argumentmaps to CMAKE_BUILD_TYPE, and supports the following modes

Note that seastar is more sensitive to allocators and optimizations thanusual. A quick rule of the thumb of the relative performances is thatrelease is 2 times faster than dev, 150 times faster than sanitize and300 times faster than debug.

It's possible to consume Seastar directly from its build directory with CMake orpkg-config.

We'll assume that the Seastar repository is located in a directory at$seastar_dir.

Viapkg-config:

$ g++ my_app.cc $(pkg-config --libs --cflags --static $seastar_dir/build/release/seastar.pc) -o my_app

and with CMake using theSeastar package:

CMakeLists.txt formy_app:

set (CMAKE_CXX_STANDARD 23)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_dir

TheCMAKE_PREFIX_PATH values ensure that CMake can locate Seastar and its compiled submodules. TheCMAKE_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:

• Seastar works with a customized version of DPDK, so by default builds and installs the DPDK submodule to$build_dir/_cooking/installed

First, configure the installation path:

$ ./configure.py --mode=release --prefix=/usr/local

then run theinstall target:

$ ninja -C build/release install

then consume it frompkg-config:

$ g++ my_app.cc $(pkg-config --libs --cflags --static seastar) -o my_app

or consume it with the sameCMakeLists.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 supportsDocker.

Use of theDPDK isoptional.

Seastar supports both C++20, and C++23. The build defaults to the lateststandard supported by your compiler, but can be explicitly selected withthe--c++-standard configure option, e.g.,--c++-standard=20,or if using CMake directly, by setting on theCMAKE_CXX_STANDARD CMakevariable.

See thecompatibity statement for more information.

There is amini tutorial and amore comprehensive one.

The documentation is available on theweb.

• Seasatar Development Mailing List: Discuss challenges, propose improvements withsending code contributions (patches), and get help from experienced developers.Subscribe or browse archives:here(or emailseastar-dev@googlegroups.com).
• GitHub Discussions: For more casual conversations and quick questions, considerusing the Seastar project'sdiscussions on Github.
• Issue Tracker: File bug reports on the project'sissue tracker.

Learn more about Seastar on the mainproject website.

Seastar comes with its ownuserspace TCP/IP stack for better performance.

• CPUs - As much as you need. SeaStar is highly friendly for multi-core and NUMA
• NICs - As fast as possible, we recommend 10G or 40G cards. It's possible to use1G too but you may be limited by their capacity.In addition, the more hardware queue per cpu the better for SeaStar.Otherwise we have to emulate that in software.
• Disks - Fast SSDs with high number of IOPS.
• Client machines - Usually a single client machine can't load our servers.Both memaslap (memcached) and WRK (httpd) cannot over load their matchingserver counter parts. We recommend running the client on different machinethan the servers and use several of them.

• cpv-cql-driver: C++ driver for Cassandra/Scylla based on seastar framework
• cpv-framework: A web framework written in c++ based on seastar framework
• redpanda: A Kafka replacement for mission critical systems
• Scylla: A fast and reliable NoSQL data store compatible with Cassandra and DynamoDB
• smf: The fastest RPC in the West
• Ceph - Crimson: Next-generation OSD (Object Storage Daemon) implementation based on the Seastar framework