From e436bc991d3e03ade6c83c1c17baf616e3cc9c62 Mon Sep 17 00:00:00 2001 From: Nat Goodspeed Date: Fri, 8 Nov 2013 18:30:11 -0500 Subject: [PATCH] Add class_heading, member_heading et al. QuickBook templates and use for cross-referencing. --- doc/attributes.qbk | 2 +- doc/barrier.qbk | 4 +- doc/condition_variables.qbk | 14 ++-- doc/fiber.qbk | 73 ++++++++++---------- doc/fibers.qbk | 132 +++++++++++++++++++++++++----------- doc/fls.qbk | 12 ++-- doc/future.qbk | 43 ++++++------ doc/mutexes.qbk | 8 +-- doc/overview.qbk | 1 + doc/packaged_task.qbk | 17 ++--- doc/promise.qbk | 15 ++-- doc/queue.qbk | 39 +++++------ doc/stack.qbk | 20 +++--- 13 files changed, 219 insertions(+), 161 deletions(-) diff --git a/doc/attributes.qbk b/doc/attributes.qbk index eed0db6e..09c55eda 100644 --- a/doc/attributes.qbk +++ b/doc/attributes.qbk @@ -31,7 +31,7 @@ fibers's context. explicit attributes( flag_unwind_t do_unwind_, flag_fpu_t preserve_fpu_) BOOST_NOEXCEPT; }; -[heading `attributes()`] +[member_heading attributes..attributes] [variablelist [[Effects:] [Default constructor using `ctx::default_stacksize()`, does unwind the stack after fiber/generator is complete and preserves FPU registers.]] diff --git a/doc/barrier.qbk b/doc/barrier.qbk index c80162d3..9bdd7aeb 100644 --- a/doc/barrier.qbk +++ b/doc/barrier.qbk @@ -15,7 +15,7 @@ barrier they must wait until all `n` fibers have arrived. Once the `n`-th fiber has reached the barrier, all the waiting fibers can proceed, and the barrier is reset. -[heading Class barrier] +[class_heading barrier] #include @@ -43,7 +43,7 @@ Instances of __barrier__ are not copyable or movable. [[Throws:] [__invalid_argument__ if `initial` is zero]] ] -[heading Member function `wait()`] +[member_heading barrier..wait] bool wait(); diff --git a/doc/condition_variables.qbk b/doc/condition_variables.qbk index 6f4bdce2..9ee15ab7 100644 --- a/doc/condition_variables.qbk +++ b/doc/condition_variables.qbk @@ -78,7 +78,7 @@ in __boost_thread__.) However, `boost::fiber::condition_variable` and form of lock. `boost::fiber::condition_variable_any` has no need to further optimize as described for `boost::thread::condition_variable`. -[heading Class `condition_variable`] +[class_heading condition_variable] #include @@ -142,7 +142,7 @@ optimize as described for `boost::thread::condition_variable`. [[Throws:] [Nothing.]] ] -[heading Member function `notify_one()`] +[member_heading condition_variable..notify_one] void notify_one(); @@ -153,7 +153,7 @@ call to `wait`, `wait_for` or `wait_until`, unblocks one of those fibers.]] [[Note:] [It is arbitrary which waiting fiber is resumed.]] ] -[heading Member function `notify_all()`] +[member_heading condition_variable..notify_all] void notify_all(); @@ -168,7 +168,7 @@ retry the wait until that state is reached. A fiber waiting on a state is reached.]] ] -[heading Templated member function `wait()`] +[template_member_heading condition_variable..wait] template< typename LockType > void wait( LockType & lk); @@ -214,8 +214,7 @@ objects. It would be like a road intersection with traffic lights disconnected from one another: sooner or later a collision will result.]] ] - -[heading Templated member function `wait_until()`] +[template_member_heading condition_variable..wait_until] template< typename LockType > cv_status wait_until( LockType & lk, clock_type::time_point const& timeout_time); @@ -259,8 +258,7 @@ predicate returns `false`, `true` otherwise.]] [[Note:] [See [*Note] for `wait()`.]] ] - -[heading Templated member function `wait_for()`] +[template_member_heading condition_variable..wait_for] template< typename LockType, typename Rep, typename Period > cv_status wait_for( LockType & lk, chrono::duration< Rep, Period > const& timeout_duration); diff --git a/doc/fiber.qbk b/doc/fiber.qbk index 81dd474d..10c490a0 100644 --- a/doc/fiber.qbk +++ b/doc/fiber.qbk @@ -154,6 +154,7 @@ method. } // okay, program continues +[#interruption] [heading Interruption] A valid fiber can be interrupted by invoking its __interrupt__ member function. @@ -187,12 +188,11 @@ __interruption_enabled__. * __cond_wait__ * __cond_wait_for__ * __cond_wait_until__ -* __barrier_wait__ * __sleep_for__ * __sleep_until__ * __interruption_point__ - +[#class_fiber_id] [heading Fiber IDs] Objects of class __fiber_id__ can be used to identify fibers. Each running @@ -209,7 +209,7 @@ not equal to any instances that refer to an actual fiber. The comparison operators on __fiber_id__ yield a total order for every non-equal __fiber_id__. - +[#class_fiber] [section:fiber Class `fiber`] #include @@ -349,7 +349,7 @@ value of `other.get_id()` prior to the assignment.]] the fiber is still joinable. See __detach__.]] ] -[heading Member function joinable] +[member_heading fiber..joinable] bool joinable() const noexcept; @@ -359,7 +359,7 @@ may not have completed; otherwise `false`.]] [[Throws:] [Nothing]] ] -[heading Member function `join()`] +[member_heading fiber..join] void join(); @@ -377,7 +377,7 @@ fiber has completed. `*this` no longer refers to any fiber of execution.]] [[Notes:] [`join()` is one of the predefined __interruption_points__.]] ] -[heading Member function `detach()`] +[member_heading fiber..detach] void detach(); @@ -391,7 +391,7 @@ associated __fiber__ object.]] [*invalid_argument]: if the fiber is not joinable.]] ] -[heading Member function `get_id()`] +[member_heading fiber..get_id] fiber::id get_id() const noexcept; @@ -400,9 +400,10 @@ associated __fiber__ object.]] __fiber_id__ that represents that fiber. Otherwise returns a default-constructed __fiber_id__.]] [[Throws:] [Nothing]] +[[See also:] [[ns_function_link this_fiber..get_id]]] ] -[heading Member function `interrupt()`] +[member_heading fiber..interrupt] void interrupt(); @@ -428,7 +429,7 @@ interruption enabled.]] `fiber::priority()`.]] ] -[heading Member function `priority()`] +[member_heading fiber..priority] int priority() const noexcept; @@ -453,6 +454,7 @@ attribute. With a scheduler that might potentially migrate a fiber from its initial thread to another, the value `true` prevents migration: the fiber will always run on its current thread. The default is `false`: normally, with an applicable scheduler, a fiber is allowed to migrate across threads.]] +[[See also:] [[ns_function_link this_fiber..thread_affinity]]] ] [heading Member function `thread_affinity()`] @@ -463,9 +465,10 @@ an applicable scheduler, a fiber is allowed to migrate across threads.]] [[Preconditions:] [`*this` refers to a fiber of execution.]] [[Returns:] [thread affinity for the fiber referenced by `*this`.]] [[Throws:] [Nothing]] +[[See also:] [[ns_function_link this_fiber..thread_affinity]]] ] -[heading Member function `operator safe_bool()`] +[member_heading fiber..operator safe_bool] operator safe_bool() const noexcept; @@ -475,7 +478,7 @@ otherwise. In effect, this is synonymous with __joinable__.]] [[Throws:] [Nothing]] ] -[heading Member function `operator!()`] +[operator_heading fiber..operator_not..operator!] bool operator!() const noexcept; @@ -485,7 +488,7 @@ otherwise.]] [[Throws:] [Nothing]] ] -[heading Member function `swap()`] +[member_heading fiber..swap] void swap( fiber & other) noexcept; @@ -499,7 +502,7 @@ prior to the call.]] [[Throws:] [Nothing]] ] -[heading Non-member function `swap()`] +[function_heading swap] void swap( fiber & l, fiber & r) noexcept; @@ -510,7 +513,7 @@ prior to the call.]] [endsect] [/ section Class fiber] - +[#class_fiber_group] [section:fiber_group Class `fiber_group`] __fiber_group__ represents a collection of fibers which can be collectively @@ -573,7 +576,7 @@ __fiber_group__ is neither copyable nor movable. [[Effects:] [Destroy `*this` and all __fiber__ objects in the group.]] ] -[heading Member function `create_fiber()`] +[member_heading fiber_group..create_fiber] template< typename Fn > fiber * create_fiber( Fn fn, attributes attrs = attributes() ); @@ -594,7 +597,7 @@ to the group.]] [[Returns:] [A pointer to the new __fiber__ object.]] ] -[heading Member function `add_fiber()`] +[member_heading fiber_group..add_fiber] void add_fiber( fiber * f); @@ -625,7 +628,7 @@ Instead, use the following: fg.add_fiber(f); } // okay, fg is now responsible for *f -[heading Member function `remove_fiber()`] +[member_heading fiber_group..remove_fiber] void remove_fiber( fiber * f); @@ -636,7 +639,7 @@ Instead, use the following: decreased by one.]] ] -[heading Member function `join_all()`] +[member_heading fiber_group..join_all] void join_all(); @@ -648,7 +651,7 @@ decreased by one.]] `join_all()` is also an interruption point.]] ] -[heading Member function `is_this_fiber_in()`] +[member_heading fiber_group..is_this_fiber_in] bool is_this_fiber_in(); @@ -657,7 +660,7 @@ decreased by one.]] `f.get_id() == this_fiber::get_id()`.]] ] -[heading Member function `is_fiber_in()`] +[member_heading fiber_group..is_fiber_in] bool is_fiber_in( fiber * f); @@ -666,7 +669,7 @@ decreased by one.]] `fx.get_id() == f->get_id()`.]] ] -[heading Member function `interrupt_all()`] +[member_heading fiber_group..interrupt_all] void interrupt_all(); @@ -674,7 +677,7 @@ decreased by one.]] [[Effects:] [Call `interrupt()` on each __fiber__ object in the group.]] ] -[heading Member function `size()`] +[member_heading fiber_group..size] int size(); @@ -686,7 +689,7 @@ decreased by one.]] [endsect] [/ section Class fiber_group] - +[#class_attributes] [section:attributes Class attributes] Class `attributes` is used to transfer parameters required to set up a @@ -737,7 +740,7 @@ fiber's context. }} -[heading Non-member function `get_id()`] +[ns_function_heading this_fiber..get_id] #include @@ -749,7 +752,7 @@ executing fiber.]] [[Throws:] [Nothing.]] ] -[heading Non-member function `sleep_until()`] +[ns_function_heading this_fiber..sleep_until] #include @@ -764,7 +767,7 @@ executing fiber.]] guarantees about how soon after `abs_time` it might resume.]] ] -[heading Non-member function `sleep_for()`] +[ns_function_heading this_fiber..sleep_for] #include @@ -781,7 +784,7 @@ exceptions. __fiber_interrupted__ if the current fiber is interrupted.]] there are no guarantees about how soon after that it might resume.]] ] -[heading Non-member function `yield()`] +[ns_function_heading this_fiber..yield] #include @@ -792,7 +795,7 @@ there are no guarantees about how soon after that it might resume.]] ] [[Throws:] [__fiber_resource_error__ if an error occurs.]] -[heading Non-member function `thread_affinity()`] +[ns_function_heading this_fiber..thread_affinity] #include @@ -800,13 +803,13 @@ there are no guarantees about how soon after that it might resume.]] void thread_affinity( bool req) noexcept; [variablelist -[[Effects:] [Set or report [link fiber_thread_affinity `fiber::thread_affinity()`] for the currently +[[Effects:] [Set or report [member_link fiber..thread_affinity] for the currently running fiber.]] [[Throws:] [Nothing.]] -[[Note:] [`fiber::thread_affinity()` is `false` by default.]] +[[Note:] [[member_link fiber..thread_affinity] is `false` by default.]] ] -[heading Non-member function interruption_point] +[ns_function_heading this_fiber..interruption_point] #include void interruption_point(); @@ -817,7 +820,7 @@ void interruption_point(); __interruption_requested__ both return `true`.]] ] -[heading Non-member function `interruption_requested()`] +[ns_function_heading this_fiber..interruption_requested] #include @@ -829,7 +832,7 @@ __interruption_requested__ both return `true`.]] [[Throws:] [Nothing.]] ] -[heading Non-member function `interruption_enabled()`] +[ns_function_heading this_fiber..interruption_enabled] #include @@ -842,7 +845,7 @@ __interruption_requested__ both return `true`.]] [[Note:][Interruption is enabled by default.]] ] -[heading Class disable_interruption] +[class_heading disable_interruption] #include @@ -882,7 +885,7 @@ value stored by the constructor of `*this`.]] ] -[heading Class `restore_interruption`] +[class_heading restore_interruption] #include diff --git a/doc/fibers.qbk b/doc/fibers.qbk index 5be12323..b10fa6ac 100644 --- a/doc/fibers.qbk +++ b/doc/fibers.qbk @@ -28,44 +28,94 @@ [def __boost_thread__ [@boost:/libs/thread/index.html Boost.Thread]] [def __async_result__ ['async-result]] -[def __blocked__ ['blocked]] -[def __interruption_points__ ['interruption-points]] +[def __blocked__ [link blocking ['blocked]]] +[def __interruption_points__ [link interruption ['interruption-points]]] [def __lockable_concept__ ['lockable concept]] [def __not_a_fiber__ ['not-a-fiber]] [def __rendezvous__ ['rendezvous]] -[def __barrier__ [link fiber.synchronization.barriers.class_barrier `barrier`]] -[def __condition__ [link fiber.conditions.class_condition_variable `condition_variable`]] +[template class_heading[class_name] +[hding class_[class_name]..Class [`[class_name]]] +] +[template class_link[class_name] [dblink class_[class_name]..[`[class_name]]]] + +[template template_heading[class_name] +[hding class_[class_name]..Template [`[class_name]<>]] +] +[template template_link[class_name] [dblink class_[class_name]..[`[class_name]<>]]] + +[template member_heading[class_name method_name] +[operator_heading [class_name]..[method_name]..[method_name]] +] +[template member_link[class_name method_name] [operator_link [class_name]..[method_name]..[method_name]]] + +[template operator_heading[class_name method_name method_text] +[hding [class_name]_[method_name]..Member function [`[method_text]]()] +] +[template operator_link[class_name method_name method_text] [dblink [class_name]_[method_name]..[`[class_name]::[method_text]()]]] + +[template template_member_heading[class_name method_name] +[hding [class_name]_[method_name]..Templated member function [`[method_name]]()] +] +[template template_member_link[class_name method_name] [member_link [class_name]..[method_name]]] + +[template static_member_heading[class_name method_name] +[hding [class_name]_[method_name]..Static member function [`[method_name]]()] +] +[template static_member_link[class_name method_name] [member_link [class_name]..[method_name]]] + +[template function_heading[function_name] +[hding [function_name]..Non-member function [`[function_name]()]] +] +[template function_link[function_name] [dblink [function_name]..[`[function_name]()]]] + +[template ns_function_heading[namespace function_name] +[hding [namespace]_[function_name]..Non-member function [`[namespace]::[function_name]()]] +] +[template ns_function_link[namespace function_name] [dblink [namespace]_[function_name]..[`[namespace]::[function_name]()]]] + +[template anchor[name] ''''''] +[template hding[name title] +''' + + '''[title]''' +''' +] +[template dblink[id text] ''''''[text]''''''] +[template `[text] ''''''[text]''''''] + +[def __barrier__ [class_link barrier]] +[def __condition__ [class_link condition_variable]] [def __coro__ ['coroutine]] [def __coro_allocator__ ['coroutine-allocator]] -[def __disable_interruption__ [link fiber.fiber_mgmt.this_fiber.class_disable_interruption `disable_interruption`]] -[def __enable_interruption__ [link fiber.fiber_mgmt.class_enable_interruption `enable_interruption`]] +[def __disable_interruption__ [class_link disable_interruption]] +[def __restore_interruption__ [class_link restore_interruption]] [def __fiber_exception__ `fiber_exception`] -[def __fiber__ [link fiber.fiber_mgmt.fiber `fiber`]] -[def __fiber_group__ [link fiber.fiber_mgmt.fiber_group `fiber_group`]] +[def __fiber__ [class_link fiber]] +[def __fiber_group__ [class_link fiber_group]] [def __fiber_interrupted__ `fiber_interrupted`] [def __fiber_resource_error__ `fiber_resource_error`] [def __fibers__ `fibers`] -[def __future__ [link fiber.synchronization.futures.future `future`]] +[def __future__ [template_link future]] [def __future_error__ `future_error`] -[def __interruption_point__ [link fiber.fiber_mgmt.this_fiber.non_member_function_interruption_point `interruption_point`]] +[def __interruption_point__ [ns_function_link this_fiber..interruption_point]] [def __invalid_argument__ `std::invalid_argument`] -[def __joinable__ [link fiber.fiber_mgmt.fiber.member_function_joinable `joinable`]] +[def __joinable__ [member_link fiber..joinable]] [def __lock_error__ `lock_error`] -[def __mutex__ `mutex`] -[def __packaged_task__ `packaged-task`] -[def __promise__ `promise`] -[def __recursive_mutex__ `recursive_mutex`] -[def __recursive_timed_mutex__ `recursive_timed_mutex`] +[def __mutex__ [class_link mutex]] +[def __packaged_task__ [template_link packaged_task]] +[def __promise__ [template_link promise]] +[def __recursive_mutex__ [class_link recursive_mutex]] +[def __recursive_timed_mutex__ [class_link recursive_timed_mutex]] [def __segmented_stack__ ['segmented-stack]] -[def __shared_future__ `shared_future`] -[def __stack_allocator_concept__ ['stack-allocator concept]] -[def __stack_allocator__ ['stack-allocator]] -[def __stack_context__ ['stack_context]] -[def __timed_mutex__ `timed_mutex`] -[def __wait__ `wait()`] -[def __wait_for__ `wait_for()`] -[def __wait_until__ `wait_until()`] +[def __shared_future__ [template_link shared_future]] +[def __stack_allocator_concept__ [link stack_allocator_concept ['stack-allocator concept]]] +[def __stack_allocator__ [class_link stack_allocator]] +[def __stack_context__ [class_link stack_context]] +[def __timed_mutex__ [class_link timed_mutex]] +[def __wait__ [member_link future..wait]] +[def __wait_for__ [member_link future..wait_for]] +[def __wait_until__ [member_link future..wait_until]] [def __no_state__ `future_errc::no_state`] [def __broken_promise__ `future_errc::broken_promise`] @@ -73,25 +123,25 @@ [def __already_satisfied__ `future_errc::future_already_satisfied`] [def __async__ `async()`] -[def __barrier_wait__ `barrier::wait()`] -[def __cond_wait__ `condition::wait()`] -[def __cond_wait_for__ `condition::wait_for()`] -[def __cond_wait_until__ `condition::wait_until()`] -[def __detach__ `fiber::detach()`] -[def __fiber_id__ `fiber::id`] -[def __fsp__ [link fiber.fls.class_fiber_specific_ptr `fiber_specific_pointer`]] -[def __future_get__ `future<>::get()`] -[def __get_id__ `fiber::get_id()`] -[def __interrupt__ `fiber::interrupt()`] -[def __interruption_enabled__ `this_fiber::interruption_enabled()`] -[def __interruption_requested__ `this_fiber::interruption_requested()`] -[def __join__ `fiber::join()`] -[def __shared_future_get__ `shared_future<>::get()`] -[def __sleep_for__ `this_fiber::sleep_for()`] -[def __sleep_until__ `this_fiber::sleep_until()`] +[def __barrier_wait__ [member_link barrier..wait]] +[def __cond_wait__ [member_link condition_variable..wait]] +[def __cond_wait_for__ [member_link condition_variable..wait_for]] +[def __cond_wait_until__ [member_link condition_variable..wait_until]] +[def __detach__ [member_link fiber..detach]] +[def __fiber_id__ [dblink class_fiber_id..`fiber::id`]] +[def __fsp__ [class_link fiber_specific_ptr]] +[def __future_get__ [member_link future..get]] +[def __get_id__ [member_link fiber..get_id]] +[def __interrupt__ [member_link fiber..interrupt]] +[def __interruption_enabled__ [ns_function_link this_fiber..interruption_enabled]] +[def __interruption_requested__ [ns_function_link this_fiber..interruption_requested]] +[def __join__ [member_link fiber..join]] +[def __shared_future_get__ [member_link shared_future..get]] +[def __sleep_for__ [ns_function_link this_fiber..sleep_for]] +[def __sleep_until__ [ns_function_link this_fiber..sleep_until]] [def __yield_context__ ['boost::asio::yield_context]] [def __yield_fiber__ ['boost::fibers::asio::yield_context]] -[def __yield__ `this_fiber::yield()`] +[def __yield__ [ns_function_link this_fiber..yield]] [def __lock__ `lock()`] [def __try_lock_for__ `try_lock_for()`] diff --git a/doc/fls.qbk b/doc/fls.qbk index 9d33fee1..e11923c0 100644 --- a/doc/fls.qbk +++ b/doc/fls.qbk @@ -22,7 +22,7 @@ __fsp__ by providing a cleanup routine `func` to the constructor. In this case, object is destroyed by invoking `func(p)`. The cleanup functions are called in an unspecified order. -[heading Class fiber_specific_ptr] +[class_heading fiber_specific_ptr] #include @@ -88,7 +88,7 @@ it.]] instance of __fsp__ has been destroyed do not call any member functions on that instance.] -[heading Member function `get()`] +[member_heading fiber_specific_ptr..get] T* get() const; @@ -99,7 +99,7 @@ instance.] [note The initial value associated with an instance of __fsp__ is `NULL` for each fiber.] -[heading Member function `operator->()`] +[operator_heading fiber_specific_ptr..operator_arrow..operator->] T* operator->() const; @@ -108,7 +108,7 @@ each fiber.] [[Throws:] [Nothing.]] ] -[heading Member function `operator*()`] +[operator_heading fiber_specific_ptr..operator_star..operator*] T& operator*() const; @@ -118,7 +118,7 @@ each fiber.] [[Throws:] [Nothing.]] ] -[heading Member function `release()`] +[member_heading fiber_specific_ptr..release] T* release(); @@ -129,7 +129,7 @@ with the current fiber without invoking the cleanup function.]] [[Throws:] [Nothing.]] ] -[heading Member function `reset()`] +[member_heading fiber_specific_ptr..reset] void reset(T* new_value=0); diff --git a/doc/future.qbk b/doc/future.qbk index cb3b3209..86628ac4 100644 --- a/doc/future.qbk +++ b/doc/future.qbk @@ -9,6 +9,7 @@ A future provides a mechanism to access the result of an asynchronous operation. +[#class_future_status] [heading Enumeration `future_status`] Timed wait-operations (__wait_for__ and __wait_until__) return the state of the future. @@ -36,7 +37,7 @@ Timed wait-operations (__wait_for__ and __wait_until__) return the state of the ] -[heading Template `future<>`] +[template_heading future] A __future__ contains a shared state which is not shared with any other future. @@ -105,7 +106,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `operator=()`] +[operator_heading future..operator_assign..operator=] future & operator=( future && other) noexcept; @@ -115,7 +116,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `swap()`] +[member_heading future..swap] void swap( future & other) noexcept; @@ -124,7 +125,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `operator safe_bool()`] +[member_heading future..operator safe_bool] operator safe_bool() const noexcept; @@ -133,7 +134,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `operator!()`] +[operator_heading future..operator_not..operator!] bool operator!() const noexcept; @@ -142,7 +143,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `valid()`] +[member_heading future..valid] bool valid() const noexcept; @@ -151,7 +152,7 @@ After construction is `false == other.valid()`]] [[Throws:] [Nothing.]] ] -[heading Member function `share()`] +[member_heading future..share] shared_future< R > share(); @@ -160,7 +161,7 @@ After construction is `false == other.valid()`]] [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Member function `get()`] +[member_heading future..get] R get(); @@ -171,7 +172,7 @@ After construction is `false == other.valid()`]] [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Member function `wait()`] +[member_heading future..wait] void wait(); @@ -180,7 +181,7 @@ After construction is `false == other.valid()`]] [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Templated member function `wait_for()`] +[template_member_heading future..wait_for] template< class Rep, class Period > future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const; @@ -191,7 +192,7 @@ After construction is `false == other.valid()`]] [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Member function `wait_until()`] +[member_heading future..wait_until] future_status wait_until( clock_type::time_point const& timeout_time) const; @@ -202,7 +203,7 @@ After construction is `false == other.valid()`]] ] -[heading Template `shared_future<>`] +[template_heading shared_future] A __shared_future__ contains a shared state which might be shared with other futures. @@ -284,7 +285,7 @@ After construction is `true == other.valid()`.]] [[Throws:] [Nothing.]] ] -[heading Member function `operator=()`] +[operator_heading shared_future..operator_assign..operator=] shared_future & operator=( future && other) noexcept; shared_future & operator=( shared_future && other) noexcept; @@ -300,7 +301,7 @@ return * this; [[Throws:] [Nothing.]] ] -[heading Member function `swap()`] +[member_heading shared_future..swap] void swap( shared_future & other) noexcept; @@ -309,7 +310,7 @@ return * this; [[Throws:] [Nothing.]] ] -[heading Member function `operator safe_bool()`] +[member_heading shared_future..operator safe_bool] operator safe_bool() const noexcept; @@ -318,7 +319,7 @@ return * this; [[Throws:] [Nothing.]] ] -[heading Member function `operator!()`] +[operator_heading shared_future..operator_not..operator!] bool operator!() const noexcept; @@ -327,7 +328,7 @@ return * this; [[Throws:] [Nothing.]] ] -[heading Member function `valid()`] +[member_heading shared_future..valid] bool valid() const noexcept; @@ -336,7 +337,7 @@ return * this; [[Throws:] [Nothing.]] ] -[heading Member function `get()`] +[member_heading shared_future..get] R get(); @@ -347,7 +348,7 @@ return * this; [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Member function `wait()`] +[member_heading shared_future..wait] void wait(); @@ -356,7 +357,7 @@ return * this; [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Templated member function `wait_for()`] +[template_member_heading shared_future..wait_for] template< class Rep, class Period > future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const; @@ -367,7 +368,7 @@ return * this; [[Throws:] [__future_error__ with error condtion __no_state__.]] ] -[heading Member function `wait_until()`] +[member_heading shared_future..wait_until] future_status wait_until( clock_type::time_point const& timeout_time) const; diff --git a/doc/mutexes.qbk b/doc/mutexes.qbk index 7935ffc6..409a6ff8 100644 --- a/doc/mutexes.qbk +++ b/doc/mutexes.qbk @@ -8,7 +8,7 @@ [section:mutex_types Mutex Types] -[heading Class `mutex`] +[class_heading mutex] #include @@ -36,7 +36,7 @@ Any fiber blocked in __lock__ is suspended in the scheduler until the owning fiber releases the lock by calling __unlock__. -[heading Class `timed_mutex`] +[class_heading timed_mutex] #include @@ -66,7 +66,7 @@ calls to __lock__, __try_lock__, __try_lock_until__, __try_lock_for__ and __unlock__ shall be permitted. -[heading Class `recursive_mutex`] +[class_heading recursive_mutex] #include @@ -96,7 +96,7 @@ each level of ownership acquired by a single fiber before ownership can be acquired by another fiber. -[heading Class `recursive_timed_mutex`] +[class_heading recursive_timed_mutex] #include diff --git a/doc/overview.qbk b/doc/overview.qbk index 1c54b722..2e763734 100644 --- a/doc/overview.qbk +++ b/doc/overview.qbk @@ -68,6 +68,7 @@ among all fibers running on the same thread. For fiber-local storage, please see __fsp__. +[#blocking] [heading Blocking] Normally, when this documentation states that a particular fiber ['blocks], it diff --git a/doc/packaged_task.qbk b/doc/packaged_task.qbk index b135be06..79ebaa28 100644 --- a/doc/packaged_task.qbk +++ b/doc/packaged_task.qbk @@ -5,6 +5,7 @@ http://www.boost.org/LICENSE_1_0.txt ] +[#class_packaged_task] [section:packaged_task Template `packaged_task<>`] A __packaged_task__ wraps a callable target that returns a value so that the @@ -91,7 +92,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator=()`] +[operator_heading packaged_task..operator_assign..operator=] packaged_task & operator=( packaged_task && other) noexcept; @@ -101,7 +102,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `swap()`] +[member_heading packaged_task..swap] void swap( packaged_task & other) noexcept; @@ -110,7 +111,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator safe_bool()`] +[member_heading packaged_task..operator safe_bool] operator safe_bool() const noexcept; @@ -119,7 +120,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator!()`] +[operator_heading packaged_task..operator_not..operator!] bool operator!() const noexcept; @@ -128,7 +129,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `valid()`] +[member_heading packaged_task..valid] bool valid() const noexcept; @@ -137,7 +138,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `get_future()`] +[member_heading packaged_task..get_future] future< R > get_future(); @@ -146,7 +147,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]] ] -[heading Member function `operator()()`] +[operator_heading packaged_task..operator_apply..operator()] void operator()(); @@ -157,7 +158,7 @@ by `fn` is stored in the shared state.]] [[Throws:] [__future_error__ with __no_state__.]] ] -[heading Member function `reset()`] +[member_heading packaged_task..reset] void reset(); diff --git a/doc/promise.qbk b/doc/promise.qbk index c223cf73..c6c22a8a 100644 --- a/doc/promise.qbk +++ b/doc/promise.qbk @@ -5,6 +5,7 @@ http://www.boost.org/LICENSE_1_0.txt ] +[#class_promise] [section:promise Template `promise<>`] A __promise__ provides a mechanism to store a value that can later be accessed @@ -83,7 +84,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator=()`] +[operator_heading promise..operator_assign..operator=] promise & operator=( promise && other) noexcept; @@ -93,7 +94,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `swap()`] +[member_heading promise..swap] void swap( promise & other) noexcept; @@ -102,7 +103,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator safe_bool()`] +[member_heading promise..operator safe_bool] operator safe_bool() const noexcept; @@ -111,7 +112,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `operator!()`] +[operator_heading promise..operator_not..operator!] bool operator!() const noexcept; @@ -120,7 +121,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [Nothing.]] ] -[heading Member function `get_future()`] +[member_heading promise..get_future] future< R > get_future(); @@ -129,7 +130,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]] ] -[heading Member function `set_value()`] +[member_heading promise..set_value] void set_value( R const& value); void set_value( R && value); @@ -139,7 +140,7 @@ ready; otherwise stores __future_error__ with error condition __broken_promise__ [[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]] ] -[heading Member function `set_exception()`] +[member_heading promise..set_exception] void set_exception( exception_ptr); diff --git a/doc/queue.qbk b/doc/queue.qbk index aa964e52..2ed36b48 100644 --- a/doc/queue.qbk +++ b/doc/queue.qbk @@ -33,6 +33,7 @@ synchonize fibers via message passing. f1.join(); f2.join(); +[#class_queue_op_status] [heading Enumeration `queue_op_status`] Queue operations return the state of the queue. @@ -71,7 +72,7 @@ Queue operations return the state of the queue. [[Effects:] [The operation did not become ready before specified timeout elapsed.]] ] -[heading Template `unbounded_queue<>`] +[template_heading unbounded_queue] #include @@ -101,7 +102,7 @@ Queue operations return the state of the queue. queue_op_status try_pop( value_type & va); }; -[heading Member function `is_closed()`] +[member_heading unbounded_queue..is_closed] bool is_closed() const; @@ -111,7 +112,7 @@ Queue operations return the state of the queue. [[Note:] [The queue is not closed by default.]] ] -[heading Member function `close()`] +[member_heading unbounded_queue..close] void close(); @@ -124,7 +125,7 @@ will return `closed`.]] that no more values will arrive.]] ] -[heading Member function `is_empty()`] +[member_heading unbounded_queue..is_empty] bool is_empty(); @@ -135,7 +136,7 @@ that no more values will arrive.]] non-empty.]] ] -[heading Member function `push()`] +[member_heading unbounded_queue..push] void push( value_type const& va); void push( value_type && va); @@ -146,7 +147,7 @@ non-empty.]] [[Throws:] [Nothing.]] ] -[heading Member function `value_pop()`] +[member_heading unbounded_queue..value_pop] queue_op_status value_pop( value_type & va); @@ -158,7 +159,7 @@ fiber gets suspended until at least one new item is `push()`ed (return value [[Throws:] [__fiber_interrupted__]] ] -[heading Member function `wait_pop()`] +[member_heading unbounded_queue..wait_pop] template< typename Rep, typename Period > queue_op_status wait_pop( value_type & va, @@ -178,7 +179,7 @@ the queue gets `close()`d (return value `closed`), or the time as reported by [[Throws:] [__fiber_interrupted__]] ] -[heading Member function `try_pop()`] +[member_heading unbounded_queue..try_pop] queue_op_status try_pop( value_type & va); @@ -190,7 +191,7 @@ dequeued value.]] ] -[heading Template `bounded_queue<>`] +[template_heading bounded_queue] #include @@ -256,7 +257,7 @@ in which `push()` or `wait_push()` calls will block (`is_full()` returns `true`) even though the number of values in the queue is less than `hwm`.]] ] -[heading Member function `is_closed()`] +[member_heading bounded_queue..is_closed] bool is_closed() const; @@ -266,7 +267,7 @@ in which `push()` or `wait_push()` calls will block (`is_full()` returns [[Note:] [The queue is not closed by default.]] ] -[heading Member function `close()`] +[member_heading bounded_queue..close] void close(); @@ -279,7 +280,7 @@ will return `closed`.]] that no more values will arrive.]] ] -[heading Member function `is_empty()`] +[member_heading bounded_queue..is_empty] bool is_empty(); @@ -290,7 +291,7 @@ that no more values will arrive.]] non-empty.]] ] -[heading Member function `is_full()`] +[member_heading bounded_queue..is_full] bool is_full(); @@ -303,7 +304,7 @@ the number of values drops below `lwm`.]] [[Note:] [This condition is transient.]] ] -[heading Member function `push()`] +[member_heading bounded_queue..push] queue_op_status push( value_type const& va); queue_op_status push( value_type && va); @@ -318,7 +319,7 @@ the fiber gets suspended until the number of values in the queue drops below [[Throws:] [__fiber_interrupted_]] ] -[heading Member function `wait_push()`] +[member_heading bounded_queue..wait_push] template< typename Rep, typename Period > queue_op_status wait_push( value_type const& va, @@ -344,7 +345,7 @@ or computed) `clock_type::time_point` (return value `timeout`).]] [[Throws:] [__fiber_interrupted_]] ] -[heading Member function `try_push()`] +[member_heading bounded_queue..try_push] queue_op_status try_push( value_type const& va); queue_op_status try_push( value_type && va); @@ -356,7 +357,7 @@ blocked on `this->value_pop()` or `this->wait_pop()` and returns `success`.]] [[Throws:] [__fiber_interrupted_]] ] -[heading Member function `value_pop()`] +[member_heading bounded_queue..value_pop] queue_op_status value_pop( value_type & va); @@ -369,7 +370,7 @@ drops below `lwm`, any fibers blocked on `push()` or `wait_push()` may resume.]] [[Throws:] [__fiber_interrupted__]] ] -[heading Member function `wait_pop()`] +[member_heading bounded_queue..wait_pop] template< typename Rep, typename Period > queue_op_status wait_pop( value_type & va, @@ -389,7 +390,7 @@ the queue gets `close()`d (return value `closed`), or the time as reported by [[Throws:] [__fiber_interrupted__]] ] -[heading Member function `try_pop()`] +[member_heading bounded_queue..try_pop] queue_op_status try_pop( value_type & va); diff --git a/doc/stack.qbk b/doc/stack.qbk index fb6b9751..d2000f8b 100644 --- a/doc/stack.qbk +++ b/doc/stack.qbk @@ -11,7 +11,7 @@ A __fiber__ uses internally a __coro__ which manages a set of registers and a st The memory used by the stack is allocated/deallocated via a __stack_allocator__ which is required to model a __stack_allocator_concept__. - +[#stack_allocator_concept] [heading __stack_allocator_concept__] A __stack_allocator__ must satisfy the __stack_allocator_concept__ requirements shown in the following table, in which `a` is an object of a @@ -42,7 +42,7 @@ to `allocate()` results in undefined behaviour.] place inside __coro__.] -[heading Class ['stack_allocator]] +[class_heading stack_allocator] __boost_coroutine__ provides the class __coro_allocator__ which models the __stack_allocator_concept__. @@ -70,7 +70,7 @@ virtual addresses are used.] void deallocate( stack_context &); } -[heading Constructor `static bool is_stack_unbound()`] +[static_member_heading stack_allocator..is_stack_unbound] static bool is_stack_unbound(); @@ -78,7 +78,7 @@ virtual addresses are used.] [[Returns:] [Returns `true` if the environment defines no limit for the size of a stack.]] ] -[heading Static member function `static std::size_t maximum_stacksize()`] +[static_member_heading stack_allocator..maximum_stacksize] static std::size_t maximum_stacksize(); @@ -87,7 +87,7 @@ virtual addresses are used.] [[Returns:] [Returns the maximum size in bytes of stack defined by the environment.]] ] -[heading Static member function `static std::size_t default_stacksize()`] +[static_member_heading stack_allocator..default_stacksize] static std::size_t default_stacksize(); @@ -97,7 +97,7 @@ virtual addresses are used.] the maximum of `64 kB` and `minimum_stacksize()`.]] ] -[heading Static member function `static std::size_t minimum_stacksize()`] +[static_member_heading stack_allocator..minimum_stacksize] static std::size_t minimum_stacksize(); @@ -106,7 +106,7 @@ the maximum of `64 kB` and `minimum_stacksize()`.]] environment: Win32 4kB, Win64 8kB, defined by rlimit on POSIX.]] ] -[heading Member function `void allocate()`] +[member_heading stack_allocator..allocate] void allocate( stack_context &, std::size_t size); @@ -121,7 +121,7 @@ on the architecture (stack grows downwards vs. upwards), the stored address is the highest/lowest address of the stack.]] ] -[heading Member function `void deallocate()`] +[member_heading stack_allocator..deallocate] void deallocate( stack_context & sctx); @@ -133,7 +133,7 @@ the highest/lowest address of the stack.]] ] -[heading Class ['stack_context]] +[class_heading stack_context] __boost_coroutine__ provides the class __stack_context__ which will contain the stack pointer and the size of the stack. @@ -149,6 +149,7 @@ structures. // for instance for segmented stacks } +[#stack_context_sp] [heading Member variable `void * sp`] [variablelist [[Value:] [Pointer to the beginning of the stack.]] @@ -156,6 +157,7 @@ structures. highest address is architecture-dependent.]] ] +[#stack_context_size] [heading Member variable `std::size_t size`] [variablelist [[Value:] [Actual size of the stack, in bytes.]]