This illustrates how to interface a synchronous Fiber function with an async
API whose notification consists of an abstract base class with virtual
success/error methods.
In essence, yield_t et al. become very like use_future_t et al. The only real
difference is the async_result return type and get() method. Factor out common
functionality into promise_completion_token and promise_handler.
Remove the boost::fibers::asio::spawn() function and its basic_yield_context
infrastructure. Fix up all existing references in example source code.
As Paul points out, links of the form [@boost:/libs/something/index.html] (as
recommended by
http://www.boost.org/doc/libs/release/doc/html/quickbook/syntax/phrase.html#quickbook.syntax.phrase.links)
do not work when generating PDF, or even when locally generating just one
library's HTML documentation. He suggests linking explicitly to the relevant
boost.org URL. This is much more satisfying as the link can be tested.
I originally assumed that a blocked bounded_channel::push() would only unblock
once the number of items in the channel dropped _below_ lwm, and described it
that way. But in fact the push unblocks as soon as the number of items in the
channel drops as low as lwm. Update documentation accordingly.
Given the documented behavior of bounded_channel(hwm, lwm), it follows that
bounded_channel(n, n) is invalid.
If the number of items in the channel == hwm, a push will block.
But if the number of items in the channel <= lwm, a push will succeed without
blocking.
Therefore, setting hwm == lwm results in a contradiction.
We intend to document that bounded_channel(hwm) is equivalent to
bounded_channel(hwm, (hwm-1)). That may or may not simplify the code, but it
certainly simplifies the reader's mental model of the relationship between the
two constructors.
However, that assertion requires that for bounded_channel(hwm), lower_bound()
in fact return (hwm-1). Test for that.
Also use BOOST_CHECK_EQUAL(a, b) instead of BOOST_CHECK(a == b) where
applicable, since the former is more informative when the test fails.
Sadly, tests on channel_op_status must still use BOOST_CHECK(a == b) --
apparently because channel_op_status, as an enum class, cannot be streamed to
std::ostream?
Make separate columns for Fiber with default synchronization and Fiber
compiled with BOOST_FIBERS_NO_ATOMICS.
Attempt to link tables to corresponding source files. Attempt does not yet
appear successful.
Add a cross-reference to shared state.
Remove doc for operator safe_bool() and operator!().
Clarify that set_exception() accepts specifically std::exception_ptr.
Explain "shared state", and provide links to the explanation wherever it's
referenced.
We don't need the doc to enumerate 'R& future<R&>::get()' or 'void
future<void>::get()' separately from 'R future<R>::get()': all three
specializations are exactly as the reader expects, given the generic
template (unlike shared_future, where it's useful to spell them out).
Encapsulate some of the necessary redundancies between future and
shared_future documentation.
Explain the effect of promise::set_value() vs. promise::set_exception() on
each of [shared_]future::get(), get_exception_ptr(), wait(), wait_for() and
wait_until().
Add get_exception_ptr() method to shared_future exposition class.
Clarify distinction between shared_future move assignment vs. copy assignment.
Document that async() is now variadic. Document its StackAllocator overload,
and the effect of passing StackAllocator. Remove warning about launch policy
'deferred' since async() has no launch policy parameter.
