The casual reader, on encountering these in the Fiber examples directory,
might otherwise assume they're intended to illustrate something about the
Fiber library.
The condition_variable examples spoke about std::lock_guard. But this doesn't
work in practice, as lock_guard has no unlock() method. Use unique_lock
instead, as test_condition.cpp does.
when_any_simple() is "simple" in the sense that we don't care about return
values or possible exceptions -- we only want to know when the shortest
subtask completes.
This source is a work in progress. We intend to add more cases.
This covers both generic callbacks (adapt_callbacks.cpp,
adapt_method_calls.cpp) and custom Asio completion tokens (yield.hpp,
promise_completion_token.hpp, detail/yield.hpp, detail/promise_handler.hpp).
Mark up the relevant source files to provide code snippets for callbacks.qbk.
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?
