ceph/src/boost/libs/fiber/doc/rationale.qbk

   1 [/
   2           Copyright Oliver Kowalke 2013.
   3  Distributed under the Boost Software License, Version 1.0.
   4     (See accompanying file LICENSE_1_0.txt or copy at
   5           http://www.boost.org/LICENSE_1_0.txt
   6 ]
   7
   8 [section:rationale Rationale]
   9
  10 [heading distinction between coroutines and fibers]
  11
  12 The fiber library extends the coroutine library by adding a scheduler and
  13 synchronization mechanisms.
  14
  15 * a coroutine yields
  16 * a fiber blocks
  17
  18 When a coroutine yields, it passes control directly to its caller (or, in the
  19 case of symmetric coroutines, a designated other coroutine). When a fiber
  20 blocks, it implicitly passes control to the fiber scheduler. Coroutines have
  21 no scheduler because they need no scheduler.[footnote
  22 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4024.pdf 'N4024:
  23 Distinguishing coroutines and fibers']].
  24
  25
  26 [heading what about transactional memory]
  27
  28 GCC supports transactional memory since version 4.7. Unfortunately tests show
  29 that transactional memory is slower (ca. 4x) than spinlocks using atomics.
  30 Once transactional memory is improved (supporting hybrid tm), spinlocks will
  31 be replaced by __transaction_atomic{} statements surrounding the critical
  32 sections.
  33
  34
  35 [heading synchronization between fibers running in different threads]
  36
  37 Synchronization classes from __boost_thread__ block the entire thread. In
  38 contrast, the synchronization classes from __boost_fiber__ block only specific
  39 fibers, so that the scheduler can still keep the thread busy running other
  40 fibers in the meantime.
  41 The synchronization classes from __boost_fiber__ are designed to be
  42 thread-safe, i.e. it is possible to synchronize fibers running in different
  43 threads as well as fibers running in the same thread. (However, there is a
  44 build option to disable cross-thread fiber synchronization support; see [link
  45 cross_thread_sync this description].)
  46
  47 [#spurious_wakeup]
  48 [heading spurious wakeup]
  49
  50 Spurious wakeup can happen when using
  51 [@http://en.cppreference.com/w/cpp/thread/condition_variable
  52 `std::condition_variable`]: the condition variable appears to be have been
  53 signaled while the awaited condition may still be false. Spurious wakeup can
  54 happen repeatedly and is caused on some multiprocessor systems where making
  55 `std::condition_variable` wakeup completely predictable would slow down all
  56 `std::condition_variable` operations.[footnote David R. Butenhof ["Programming
  57 with POSIX Threads]]
  58
  59 __condition__ is not subject to spurious wakeup. Nonetheless it is
  60 prudent to test the business-logic condition in a `wait()` loop [mdash] or,
  61 equivalently, use one of the `wait( lock, predicate )` overloads.
  62
  63 See also [link condition_variable_spurious_wakeups No Spurious Wakeups].
  64
  65
  66 [heading migrating fibers between threads]
  67
  68 Support for migrating fibers between threads has been integrated. The
  69 user-defined scheduler must call __context_detach__ on a fiber-context on the
  70 source thread and __context_attach__ on the destination thread, passing the
  71 fiber-context to migrate. (For more information about custom schedulers, see
  72 [link custom Customization].)
  73 Examples `work_sharing` and `work_stealing` in directory `examples` might be
  74 used as a blueprint.
  75
  76 See also [link migration Migrating fibers between threads].
  77
  78
  79 [heading support for Boost.Asio]
  80
  81 Support for __boost_asio__[s] __async_result__ is not part of the official API.
  82 However, to integrate with a __io_service__, see [link integration Sharing a
  83 Thread with Another Main Loop]. To interface smoothly with an arbitrary Asio
  84 async I/O operation, see [link callbacks_asio Then There[s] __boost_asio__].
  85
  86 [heading tested compilers]
  87
  88 The library was tested with GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++11-mode.
  89
  90
  91 [heading supported architectures]
  92
  93 __boost_fiber__ depends on __boost_context__ - the list of supported architectures
  94 can be found [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/architectures.html here].
  95
  96
  97 [endsect]