Add a link to the section "No Spurious Wakeups" in the condition_variable
section.
Make a pass over "migrating fibers between threads," adding a link to the
whole new section on that same topic.
Highlight predicate condition_variable::wait() method in condition_variable
front matter.
Rewrite the explanation of wait()'s Precondition.
Add a condition_variables subsection about no spurious condition_variable
wakeups. Remove "or spuriously" from wakeup conditions in wait*() methods.
First pass through "spurious wakeup" section in Rationale.
First pass through migration.qbk. Use lock_t throughout work_sharing.cpp,
instead of lock_t, lock_count and explicit std::unique_lock<std::mutex>
declarations. Unify treatment of main and dispatcher fibers.
Clarify thread-safety requirements on sched_algorithm::notify() and
suspend_until().
Clarify disable_interruption when rethrowing fiber_interrupted.
Consolidate future<T>::get(): returns T whether T is R, R& or void.
Mention nesting of disable_interruption (which matters) versus nesting of
restore_interruption (which doesn't). Mention that a disable_interruption
constructed within the scope of another disable_interruption is a no-op, both
itself and when passed to restore_interruption.
When packaged_task::operator()() stores a value or an exception, state "as if"
by promise::set_value() or set_exception(): the shared state is set ready.
Similarly for ~packaged_task() and ~promise() setting broken_promise.
Sprinkle links to the Allocator concept, std::allocator and
std::allocator_arg_t where referenced. Similarly for StackAllocator.
Add more cross-reference links where Fiber classes and methods are mentioned.
Also things like std::unique_lock and std::mutex.
Clarify error condition for value_pop() when channel is close()d.
Since fiber_specific_ptr::release() does not invoke cleanup, it should not
throw an exception raised during cleanup.
Document boost::fibers::scheduler::ready_queue_t and expand on the
context::ready_link(), ready_unlink() and ready_is_linked() methods.
Explain migrate() restrictions on is_main_context() and
is_dispatcher_context() context instances.
There's a blanket statement under 'Exceptions' that any exception not caught
by a running fiber will cause the program to terminate. fiber_interrupted is
an exception to this rule: that exception will terminate the fiber, but not
the whole program.
Explain that when a fiber running packaged_task is terminated by
fiber_interrupted, and another fiber calls future::get() on the future from
that packaged_task, fiber_interrupted will be rethrown regardless of
disable_interruption. This is implicit in existing material, but worth making
explicit.
Explicitly state that a thread's main fiber may call (e.g.) this_fiber::yield().
[un]bounded_channel::try_{push,pop}() are not interruption_points. Remove them
from the big list.
Semantics of operator<(fiber, fiber) depend solely on operator<(fiber::id,
fiber::id). Restating semantics of the latter function not needed.
Add a note clarifying the phrase "timeout-related exceptions."
Wrap the full descriptive text for both classes in a QuickBook template
parameterized with class name and appropriate substitutions for the (few)
differences between the two classes.
Note effect of BOOST_USE_SEGMENTED_STACKS if StackAllocator is not explicitly
passed.
Introduce function_heading_for QuickBook template to allow separate
descriptions of swap(fiber), swap(packaged_task) and swap(promise).
Document async() using C++14 std::result_of_t and std::decay_t, aligning with
std::async() documentation.
Rework when_any / when_all examples to use unbounded_channel throughout, since
we always close() the channel after the first value anyway. bounded_channel
doesn't really add much value here.
Make wait_first_outcome_impl() infer its channel pointer type. That way we can
reuse that function instead of coding a separate wait_all_until_error_impl(),
which differs only in using the nchannel facade instead of directly pushing to
unbounded_channel.
Explain use of std::bind() to bind a lambda.
Use a more nuanced discussion of promise lifetime in write_ec() example
function.
Use condition_variable::wait(lock, predicate) in a couple places in
work_sharing.cpp example.
Add a note to the condition_variable::wait_for(..., pred) overload.
fiber_specific_ptr::reset() has no default argument.
Remove mention of launch policy deferred, since no API accepts a launch
policy argument.
Copy construction or copy assignment of a shared_future leaves other.valid()
unchanged. It won't be 'true' unless it was 'true' before.
Mention that [shared_]future::get_exception_ptr() does not invalidate.
Note that 'blocks' and 'suspends' are used interchangeably.
Add some cross-references; add link to std::allocator_arg_t. Clarify the
cross-reference to the paragraph describing BOOST_FIBERS_NO_ATOMICS.
Reformat some overly-long source lines.
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.
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.
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.
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.
Well, almost the same: bounded_channel pop operations include the note about
unblocking blocked push operations. Parameterize xchannel_pop (et al.) to
allow this divergence between unbounded_channel and bounded_channel pop
methods.
The descriptions of [un]bounded_channel::push() and the other push variants
are very similar, and must be kept consistent. Similarly, all the pop variants
must be kept consistent. Use QuickBook templates to supply much of the wording
for these methods.
Add note explaining why synchronization objects can neither be moved nor
copied.
Introduce line breaks for some code lines that get broken strangely by doc
toolchain.
Eliminate reference to mutex::scoped_lock.
