ceph/src/seastar/README.md

   1 Seastar
   2 =======
   3
   4 [![CircleCI](https://circleci.com/gh/scylladb/seastar.svg?style=svg)](https://circleci.com/gh/scylladb/seastar)
   5 [![Version](https://img.shields.io/github/tag/scylladb/seastar.svg?label=version&colorB=green)](https://github.com/scylladb/seastar/releases)
   6 [![License: Apache2](https://img.shields.io/github/license/scylladb/seastar.svg)](https://github.com/scylladb/seastar/blob/master/LICENSE)
   7 [![n00b issues](https://img.shields.io/github/issues/scylladb/seastar/n00b.svg?colorB=green)](https://github.com/scylladb/seastar/labels/n00b)
   8
   9 Introduction
  10 ------------
  11
  12 SeaStar is an event-driven framework allowing you to write non-blocking,
  13 asynchronous code in a relatively straightforward manner (once understood).
  14 It is based on [futures](http://en.wikipedia.org/wiki/Futures_and_promises).
  15
  16 Building Seastar
  17 --------------------
  18
  19 For more details and alternative work-flows, read [HACKING.md](./HACKING.md).
  20
  21 Assuming that you would like to use system packages (RPMs or DEBs) for Seastar's dependencies, first install them:
  22
  23 ```
  24 $ sudo ./install-dependencies.sh
  25 ```
  26
  27 then configure (in "release" mode):
  28
  29 ```
  30 $ ./configure.py --mode=release
  31 ```
  32 then compile:
  33
  34 ```
  35 $ ninja -C build/release
  36 ```
  37
  38 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.
  39
  40 For example, to fetch `fmt` locally, configure Seastar like this:
  41
  42 ```
  43 $ ./configure.py --mode=dev --cook fmt
  44 ```
  45
  46 `--cook` can be repeated many times for selecting multiple dependencies.
  47
  48
  49 Build modes
  50 ----------------------------------------------------------------------------
  51
  52 The configure.py script is a wrapper around cmake. The --mode argument
  53 maps to CMAKE_BUILD_TYPE, and supports the following modes
  54
  55 |          | CMake mode          | Debug info | Optimi&shy;zations | Sanitizers   | Allocator | Checks   | Use for                                |
  56 | -------- | ------------------- | ---------- | ------------------ |------------- | --------- | -------- | -------------------------------------- |
  57 | debug    | `Debug`             | Yes        | `-O0`              | ASAN, UBSAN  | System    | All      | gdb                                    |
  58 | release  | `RelWithDebInfo`    | Yes        | `-O3`              | None         | Seastar   | Asserts  | production                             |
  59 | dev      | `Dev` (Custom)      | No         | `-O1`              | None         | Seastar   | Asserts  | build and test cycle                   |
  60 | sanitize | `Sanitize` (Custom) | Yes        | `-Os`              | ASAN, UBSAN  | System    | All      | second level of tests, track down bugs |
  61
  62 Note that seastar is more sensitive to allocators and optimizations than
  63 usual. A quick rule of the thumb of the relative performances is that
  64 release is 2 times faster than dev, 150 times faster than sanitize and
  65 300 times faster than debug.
  66
  67 Using Seastar from its build directory (without installation)
  68 ----------------------------------------------------------------------------
  69
  70 It's possible to consume Seastar directly from its build directory with CMake or `pkg-config`.
  71
  72 We'll assume that the Seastar repository is located in a directory at `$seastar_dir`.
  73
  74
  75 Via `pkg-config`:
  76
  77 ```
  78 $ g++ my_app.cc $(pkg-config --libs --cflags --static $seastar_dir/build/release/seastar.pc) -o my_app
  79 ```
  80
  81 and with CMake using the `Seastar` package:
  82
  83
  84 `CMakeLists.txt` for `my_app`:
  85
  86 ```
  87 find_package (Seastar REQUIRED)
  88
  89 add_executable (my_app
  90   my_app.cc)
  91
  92 target_link_libraries (my_app
  93   Seastar::seastar)
  94 ```
  95
  96 ```
  97 $ mkdir $my_app_dir/build
  98 $ cd $my_app_dir/build
  99 $ cmake -DCMAKE_PREFIX_PATH="$seastar_dir/build/release;$seastar_dir/build/release/_cooking/installed" -DCMAKE_MODULE_PATH=$seastar_dir/cmake $my_app_dir
 100 ```
 101
 102 The `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.
 103
 104 Using an installed Seastar
 105 --------------------------------
 106
 107 You can also consume Seastar after it has been installed to the file-system.
 108
 109 **Important:**
 110
 111 - Seastar works with a customized version of DPDK, so by default builds and installs the DPDK submodule to `$build_dir/_cooking/installed`
 112
 113 First, configure the installation path:
 114
 115 ```
 116 $ ./configure.py --mode=release --prefix=/usr/local
 117 ```
 118
 119 then run the `install` target:
 120
 121 ```
 122 $ ninja -C build/release install
 123 ```
 124
 125 then consume it from `pkg-config`:
 126
 127 ```
 128 $ g++ my_app.cc $(pkg-config --libs --cflags --static seastar) -o my_app
 129 ```
 130
 131 or consume it with the same `CMakeLists.txt` as before but with a simpler CMake invocation:
 132
 133 ```
 134 $ cmake ..
 135 ```
 136
 137 (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`.)
 138
 139 There are also instructions for building on any host that supports [Docker](doc/building-docker.md).
 140
 141 Use of the [DPDK](http://dpdk.org) is [optional](doc/building-dpdk.md).
 142
 143 #### Seastar's C++ dialect: C++17 or C++20
 144
 145 Seastar supports both C++17, and C++20. The build defaults to the latest
 146 dialect supported by your compiler, but can be explicitly selected with
 147 the `--c++-dialect` configure option, e.g., `--c++-dialect=gnu++17`,
 148 or if using CMake directly, by setting on the `Seastar_CXX_DIALECT` CMake
 149 variable.
 150
 151 See the [compatibity statement](doc/compatibility.md) for more information.
 152
 153 Getting started
 154 ---------------
 155
 156 There is a [mini tutorial](doc/mini-tutorial.md) and a [more comprehensive one](doc/tutorial.md).
 157
 158 The documentation is available on the [web](http://docs.seastar.io/master/index.html).
 159
 160
 161 Resources
 162 ---------
 163 Ask questions and post patches on the development mailing list. Subscription
 164 information and archives are available [here](https://groups.google.com/forum/#!forum/seastar-dev),
 165 or just send an email to seastar-dev@googlegroups.com.
 166
 167 Information can be found on the main [project website](http://seastar.io).
 168
 169 File bug reports on the project [issue tracker](https://github.com/scylladb/seastar/issues).
 170
 171 The Native TCP/IP Stack
 172 -----------------------
 173
 174 Seastar comes with its own [userspace TCP/IP stack](doc/native-stack.md) for better performance.
 175
 176 Recommended hardware configuration for SeaStar
 177 ----------------------------------------------
 178
 179 * CPUs - As much as you need. SeaStar is highly friendly for multi-core and NUMA
 180 * NICs - As fast as possible, we recommend 10G or 40G cards. It's possible to use
 181        1G too but you may be limited by their capacity.
 182        In addition, the more hardware queue per cpu the better for SeaStar.
 183        Otherwise we have to emulate that in software.
 184 * Disks - Fast SSDs with high number of IOPS.
 185 * Client machines - Usually a single client machine can't load our servers.
 186        Both memaslap (memcached) and WRK (httpd) cannot over load their matching
 187        server counter parts. We recommend running the client on different machine
 188        than the servers and use several of them.
 189
 190 Projects using Seastar
 191 ----------------------------------------------
 192
 193 * [cpv-cql-driver](https://github.com/cpv-project/cpv-cql-driver): C++ driver for Cassandra/Scylla based on seastar framework
 194 * [cpv-framework](https://github.com/cpv-project/cpv-framework): A web framework written in c++ based on seastar framework
 195 * [redpanda](https://vectorized.io/): A Kafka replacement for mission critical systems
 196 * [Scylla](https://github.com/scylladb/scylla): A fast and reliable NoSQL data store compatible with Cassandra and DynamoDB
 197 * [smf](https://github.com/smfrpc/smf): The fastest RPC in the West