diff --git a/doc/callbacks.qbk b/doc/callbacks.qbk index f4c68b3d..33aab53e 100644 --- a/doc/callbacks.qbk +++ b/doc/callbacks.qbk @@ -127,6 +127,7 @@ The source code above is found in and [@../../examples/adapt_method_calls.cpp adapt_method_calls.cpp]. +[#callbacks_asio] [heading Then There's __boost_asio__] [import ../examples/asio/yield.hpp] diff --git a/doc/fiber.qbk b/doc/fiber.qbk index 304c4930..08801784 100644 --- a/doc/fiber.qbk +++ b/doc/fiber.qbk @@ -73,7 +73,7 @@ cooperatively by a scheduler. Objects of type __fiber__ are move-only. A new fiber is launched by passing an object of a callable type that can be invoked with no parameters. -If the object must not (or cannot) be copied, then ['std::ref] can be used to +If the object must not be copied or moved, then ['std::ref] can be used to pass in a reference to the function object. In this case, the user must ensure that the referenced object outlives the newly-created fiber. @@ -118,7 +118,12 @@ mutex], or [class_link condition_variable], or any of the other [link synchronization synchronization objects] provided by the library. If a detached fiber is still running when the thread's main fiber terminates, -that fiber will be [link interruption interrupted] and shut down. +that fiber will be [link interruption interrupted] and shut down.[footnote +This treatment of detached fibers depends on a detached fiber eventually +either terminating or reaching one of the specified __interruption_points__. +Note that since [ns_function_link this_fiber..yield] is ['not] an interruption +point, a detached fiber whose only interaction with the Fiber library is +`yield()` cannot cleanly be terminated.] [heading Joining] diff --git a/doc/overview.qbk b/doc/overview.qbk index 07b246b3..38d4ca65 100644 --- a/doc/overview.qbk +++ b/doc/overview.qbk @@ -95,8 +95,9 @@ Use __future__ instead. Similarly, a fiber that invokes a normal blocking I/O operation will block its entire thread. Fiber authors are encouraged to consistently use asynchronous -I/O. __boost_asio__ explicitly supports fibers; other asynchronous I/O -operations can straightforwardly be adapted for __boost_fiber__. +I/O. __boost_asio__ and other asynchronous I/O operations can +straightforwardly be adapted for __boost_fiber__: see [link callbacks +Integrating Fibers with Asynchronous Callbacks]. [warning This library is ['not] an official Boost library.] diff --git a/doc/rationale.qbk b/doc/rationale.qbk index 1b66c2df..18079bb4 100644 --- a/doc/rationale.qbk +++ b/doc/rationale.qbk @@ -58,27 +58,27 @@ memory access. A more [*important] aspect is the problem with thread-local-storage ([*TLS]). Instead of recomputing the address of a TLS variable, a compiler might, as an -optimization, reuse its previously-computed address -[footnote dicussed in [@http://www.crystalclearsoftware.com/soc/coroutine/coroutine/coroutine_thread.html +optimization, cache its previously-computed address in various function stack +frames.[footnote dicussed in +[@http://www.crystalclearsoftware.com/soc/coroutine/coroutine/coroutine_thread.html 'Interaction between coroutines and threads' by Giovanni P. Deretta, [@https://groups.google.com/a/isocpp.org/forum/#!topic/std-proposals/3g6ZIWedGJ8 -'A proposal to add coroutines to C++']]]. - +'A proposal to add coroutines to C++']]] +If a fiber was running on thread ['t0] and then migrated to thread ['t1], the +cached TLS variable address(es) would continue pointing to the TLS for thread +['t0]. Bad things would ensue. [heading support for Boost.Asio] -The support for Boost.Asio's __async_result__ is not part of the official API -(implementation provided in example section). -__async_result__ does not reflect that __boost_fiber__ itself uses an internal -scheduler (especially fibers not in touch with code using __boost_asio__, for -instance a sleeping fiber will not be launched explicitly by __boost_asio__). -The integration of __boost_fiber__ into __boost_asio__ requires some investigation -from both authors. - +Support for __boost_asio__'s __async_result__ is not part of the official API. +However, to integrate with a `boost::asio::io_service`, see [link integration +Sharing a Thread with Another Main Loop]. To interface smoothly with an +arbitrary Asio async I/O operation, see [link callbacks_asio Then There's +__boost_asio__]. [heading tested compilers] -The library was tested with GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++14-mode. +The library was tested with GCC-4.9.2, GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++14-mode. [heading supported architectures]