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