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 | Optimizations  | 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++14 or C++17
 144
 145 Seastar supports both C++14, and C++17. Some newer features and optimizations
 146 may only be available to C++17, so users are encouraged to use C++17 when
 147 possible. By default Seastar builds with the C++17 dialect, but a C++14
 148 compilation can be requested with a `./configure.py --c++-dialect=gnu++14`
 149 or, if using CMake directly, by setting on the `Seastar_CXX_DIALECT` CMake
 150 variable to `"gnu++14"`.
 151
 152 However, by default Seastar uses C++14-compatible types such as
 153 `std::experimental::optional<>`, `boost::variant` and `std::experimental::string_view`, both internally and in its public
 154 API, thus forcing them on C++17 projects. To fix this, Seastar respects the value of the preprocessor variable
 155 `SEASTAR_USE_STD_OPTIONAL_VARIANT_STRINGVIEW`, which changes those types to their `stdlib` incarnation, and allows
 156 seemless use of C++17. Usage of this option requires an updated compiler, such
 157 as GCC 8.1.1-5 on Fedora.
 158
 159 Getting started
 160 ---------------
 161
 162 There is a [mini tutorial](doc/mini-tutorial.md) and a [more comprehensive one](doc/tutorial.md).
 163
 164 The documentation is available on the [web](http://docs.seastar.io/master/index.html).
 165
 166
 167 Resources
 168 ---------
 169 Ask questions and post patches on the development mailing list. Subscription
 170 information and archives are available [here](https://groups.google.com/forum/#!forum/seastar-dev),
 171 or just send an email to seastar-dev@googlegroups.com.
 172
 173 Information can be found on the main [project website](http://seastar.io).
 174
 175 File bug reports on the project [issue tracker](https://github.com/scylladb/seastar/issues).
 176
 177 The Native TCP/IP Stack
 178 -----------------------
 179
 180 Seastar comes with its own [userspace TCP/IP stack](doc/native-stack.md) for better performance.
 181
 182 Recommended hardware configuration for SeaStar
 183 ----------------------------------------------
 184
 185 * CPUs - As much as you need. SeaStar is highly friendly for multi-core and NUMA
 186 * NICs - As fast as possible, we recommend 10G or 40G cards. It's possible to use
 187        1G too but you may be limited by their capacity.
 188        In addition, the more hardware queue per cpu the better for SeaStar.
 189        Otherwise we have to emulate that in software.
 190 * Disks - Fast SSDs with high number of IOPS.
 191 * Client machines - Usually a single client machine can't load our servers.
 192        Both memaslap (memcached) and WRK (httpd) cannot over load their matching
 193        server counter parts. We recommend running the client on different machine
 194        than the servers and use several of them.
 195
 196 Projects using Seastar
 197 ----------------------------------------------
 198
 199 * [cpv-cql-driver](https://github.com/cpv-project/cpv-cql-driver): C++ driver for Cassandra/Scylla based on seastar framework
 200 * [cpv-framework](https://github.com/cpv-project/cpv-framework): A web framework written in c++ based on seastar framework
 201 * [redpanda](https://vectorized.io/): A Kafka replacement for mission critical systems
 202 * [Scylla](https://github.com/scylladb/scylla): A fast and reliable NoSQL data store compatible with Cassandra and DynamoDB
 203 * [smf](https://github.com/smfrpc/smf): The fastest RPC in the West