ceph/src/seastar/doc/compatibility.md

   1 Compatibility
   2 =============
   3
   4 As a library, Seastar aims to maintain backwards compatibility
   5 in terms of the source (application code should continue to
   6 build with newer versions of Seastar) and any binary protocols
   7 that Seastar exposes (e.g. rpc).
   8
   9 Link compatibility is not maintained - you cannot link an
  10 application built with one version of Seastar with another
  11 version of Seastar.
  12
  13 Language dialects
  14 =================
  15
  16 Seastar will support the last two standards approved by the
  17 ISO C++ committee. For example, after C++20 is released,
  18 Seastar supports C++17 and C++20.  Similarly, when C++23 is released,
  19 Seastar will support C++20 and C++23.
  20
  21 Some features may only be enabled for newer dialects.
  22
  23
  24 Platforms
  25 =========
  26
  27 Seastar supports Linux. There is no known minimum kernel version,
  28 but very old kernels might not work. Performance can be significantly
  29 better for newer kernels.
  30
  31 Filesystem implementation quality can have significant effect on
  32 file I/O performance. XFS is known to be working, ext4 may work well
  33 too. Test your filesystem and kernel versions to be sure.
  34
  35 Patches for new platforms (e.g, Windows) are welcome.
  36
  37
  38 Compilers
  39 =========
  40
  41 Seastar supports gcc and clang. Ports to other compilers are
  42 welcome.
  43
  44 The last two major releases of a compiler are supported (e.g.
  45 gcc 9 and gcc 10). Patches to support older versions are welcome,
  46 as long as they don't require onerous compromises.
  47
  48 Deprecation
  49 ===========
  50
  51 Occasionally, we discover that we took the wrong approach with
  52 an API. In these cases we will offer a new API and tag the old
  53 API with the [[deprecated]] attribute. The deprecated API will
  54 be removed after a transition period (which can vary depending on
  55 how central the deprecated API is).
  56
  57 Breaking changes
  58 ================
  59
  60 Rarely, we have to make breaking changes. We try to limit those,
  61 but sometimes there is no choice.
  62
  63 To support a transition period for breaking changes, Seastar
  64 offers the Seastar_API_LEVEL cmake variable (and corresponding
  65 --api-level configure.py option). An API level selects different
  66 versions of the API. For example.
  67
  68    - Seastar_API_LEVEL=1 selects an old version of the
  69      server_socket::accept() API that returns a variadic
  70      future (which is deprecated)
  71    - Seastar_API_LEVEL=2 selects a new version of the
  72      server_socket::accept() API that returns a non-variadic
  73      future
  74    - Seastar_API_LEVEL=6 makes futures non-variadic
  75
  76 Applications can use an old API_LEVEL during a transition
  77 period, fix their code, and move to the new API_LEVEL.
  78
  79 Old API levels only live for a transition period, so if
  80 you are using an API level below the latest, you should
  81 upgrade quickly.
  82
  83 Note the application should not refer to the `api_vN`
  84 sub-namespaces that Seastar defines as part of the API_LEVEL
  85 mechanism; these are internal.
  86
  87 Internal namespace
  88 ==================
  89
  90 Identifiers in the `seastar::internal` namespace are not subject
  91 to source level compatibility and are subject to change or removal
  92 without notice. In addition the `api_vN` sub-namespaces are also
  93 internal.
  94
  95 Accidentally exposed internal identifiers
  96 =========================================
  97
  98 Some identifiers predate the internal namespace, and are only
  99 exposed accidentally. These can also be removed or changed. Exposed
 100 identifiers are documented using doxygen, but not all exposed
 101 APIs are documented. In case of doubt, ask on the mailing list.
 102
 103
 104 API Level History
 105 =================
 106
 107 |Level|Introduced |Mandatory|Description                                   |
 108 |:---:|:---------:|:-------:| -------------------------------------------- |
 109 | 2   |  2019-07  | 2020-04 | Non-variadic futures in socket::accept()     |
 110 | 3   |  2020-05  |         | make_file_data_sink() closes file and returns a future<>  |
 111 | 4   |  2020-06  |         | Non-variadic futures in when_all_succeed()   |
 112
 113
 114 Note: The "mandatory" column indicates when backwards compatibility
 115 support for the API preceding the new level was removed.
 116
 117 Implementation notes for API levels
 118 ===================================
 119
 120 API levels are implemented by defining internal sub-namespaces
 121 for each API level: `seastar::api_v1`, `seatar::api_v2` etc. `#ifdef`s
 122 are used to inline the user-selected API level namespace into the
 123 main `seastar` namespace, making it visible.
 124
 125 Usually, the old API is implemented in terms of the new API to
 126 avoid code duplication.
 127
 128 Here is an example about the transition from API_LEVEL 1 to 2. The
 129 transition from 2 to 3 and similar is analogous.
 130
 131 Unconditionally:
 132  - the new API is defined in sub-namespace `api_v2`
 133
 134 If API_LEVEL is 2:
 135  - `api_v2` namespace is inlined into the `seastar` namespace
 136
 137 If API_LEVEL is 1:
 138  - the old API is defined in sub-namespace `api_v1`
 139  - `api_v1` is implemented in terms of `api_v2` to prevent code duplication
 140  - `api_v1` namespace is inlined into the `seastar` namespace
 141
 142 After a transition period:
 143  - everthing in `api_v1` is dropped
 144  - `api_v2` is removed, and its contents is placed in the parent namespace