|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r57827 - sandbox/fiber/libs/fiber/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-11-20 20:29:58
Author: olli
Date: 2009-11-20 20:29:57 EST (Fri, 20 Nov 2009)
New Revision: 57827
URL: http://svn.boost.org/trac/boost/changeset/57827
Log:
- quickbook documents corrected
Text files modified:
sandbox/fiber/libs/fiber/doc/fiber_ref.qbk | 998 +++++++++++++--------------------------
sandbox/fiber/libs/fiber/doc/lockables.qbk | 538 ++++++++++----------
2 files changed, 606 insertions(+), 930 deletions(-)
Modified: sandbox/fiber/libs/fiber/doc/fiber_ref.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/fiber_ref.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/fiber_ref.qbk 2009-11-20 20:29:57 EST (Fri, 20 Nov 2009)
@@ -7,789 +7,461 @@
[section:fiber_management Fiber Management]
+ [heading Synopsis]
-[heading Synopsis]
+ Each __fiber__ class represents a user-space context of execution which will be launched and managed by the
+ __scheduler__ class. Objects of type __fiber__ are copy- and moveable.
-Each __fiber__ class represents a user-space context of execution which will be launched and managed by the
-__scheduler__ class. Objects of type __fiber__ are copy- and moveable.
+ boost::fiber f; // not-a-fiber
- boost::fiber f; // not-a-fiber
+ void f()
+ {
+ boost::fiber f1=boost::fibers::make_fiber( some_fn);
+ boost::fiber f2=boost::fibers::make_fiber( another_fn);
- void f()
- {
- boost::fiber f1=boost::fibers::make_fiber( some_fn);
- boost::fiber f2=boost::fibers::make_fiber( another_fn);
+ boost::fibers::scheduler s;
+ s.submit( f1); // f1 gets copied
+ s.submit( boost::move( f2) ); // f2 gets moved
- boost::fibers::scheduler s;
- s.submit( f1); // f1 gets copied
- s.submit( boost::move( f2) ); // f2 gets moved
+ std::cout << f1.get_id() << std::endl;
+ std::cout << f2.get_id() << std::endl;
+ }
- std::cout << f1.get_id() << std::endl;
- std::cout << f2.get_id() << std::endl;
- }
+ [heading Launching fibers]
-[heading Launching fibers]
+ A new fiber is launched by passing an object of a callable type that can be invoked with no parameters to the
+ constructor and submiting the fiber (copy- or move-op.) to an instance of __scheduler__. The object is then copied
+ into internal storage, and invoked on the newly-created fiber. If the object must not (or cannot) be copied, then
+ `boost::ref` can be used to pass in a reference to the function object. In this case, the user of __boost_fiber__
+ must ensure that the referred-to object outlives the newly-created fiber.
-A new fiber is launched by passing an object of a callable type that can be invoked with no parameters to the
-constructor and submiting the fiber (copy- or move-op.) to an instance of __scheduler__. The object is then copied
-into internal storage, and invoked on the newly-created fiber. If the object must not (or cannot) be copied, then
-`boost::ref` can be used to pass in a reference to the function object. In this case, the user of __boost_fiber__
-must ensure that the referred-to object outlives the newly-created fiber.
+ struct callable
+ { void operator()(); };
- struct callable
- { void operator()(); };
+ boost::fiber copies_are_safe()
+ {
+ callable x;
+ return boost::fiber( x);
+ } // x is destroyed, but the newly-created fiber has a copy, so this is OK
- boost::fiber copies_are_safe()
- {
- callable x;
- return boost::fiber( x);
- } // x is destroyed, but the newly-created fiber has a copy, so this is OK
+ boost::fiber oops()
+ {
+ callable x;
+ return boost::fiber( boost::ref( x) );
+ } // x is destroyed, but the newly-created fiber still has a reference
+ // this leads to undefined behaviour
- boost::fiber oops()
- {
- callable x;
- return boost::fiber( boost::ref( x) );
- } // x is destroyed, but the newly-created fiber still has a reference
- // this leads to undefined behaviour
+ If you wish to construct an instance of __fiber__ with a function or callable object that requires arguments to be
+ supplied, this can be done by passing additional arguments to the __fiber__ constructor:
-If you wish to construct an instance of __fiber__ with a function or callable object that requires arguments to be
-supplied, this can be done by passing additional arguments to the __fiber__ constructor:
+ void find_the_question( int the_answer);
- void find_the_question( int the_answer);
+ boost::fiber deep_thought_2( find_the_question, 42);
- boost::fiber deep_thought_2( find_the_question, 42);
+ The arguments are ['copied] into the internal fiber structure: if a reference is required, use `boost::ref`, just as
+ for references to callable functions.
-The arguments are ['copied] into the internal fiber structure: if a reference is required, use `boost::ref`, just as
-for references to callable functions.
+ For convinience `boost::fibers::make_fiber()` is provided:
-For convinience `boost::fibers::make_fiber()` is provided:
+ boost::fiber f = boost::fibers::make_fiber( new_fn, arg1, arg2, arg3);
- boost::fiber f = boost::fibers::make_fiber( new_fn, arg1, arg2, arg3);
+ Another alternative is to use __scheduler_make_fiber__ which creates and stores the new fiber inside the scheduler.
-Another alternative is to use __scheduler_make_fiber__ which creates and stores the new fiber inside the scheduler.
+ boost::fibers::scheduler sched;
+ sched.make_fiber( new_fn, arg1, arg2, arg3);
- boost::fibers::scheduler sched;
- sched.make_fiber( new_fn, arg1, arg2, arg3);
+ [heading Exceptions in fiber functions]
-[heading Exceptions in fiber functions]
+ Exceptions thrown by the function or callable object passed to the __fiber__ constructor are consumed by the
+ framework (if it required to know whichexceptions was thrown __boost_task__ should be used together with
+ __boost_fiber__).
-Exceptions thrown by the function or callable object passed to the __fiber__ constructor are consumed by the
-framework (if it required to know whichexceptions was thrown __boost_task__ should be used together with
-__boost_fiber__).
+ [heading Joining]
-[heading Joining]
+ In order to wait for a fiber to finish, the __join__ member functions of the __fiber__ object can be
+ used. __join__ will block the calling fiber until the fiber represented by the __fiber__ object has completed.
+ If the fiber has already completed, or the __fiber__ object represents __not_a_fiber__, then __join__ returns
+ immediately.
-In order to wait for a fiber to finish, the __join__ member functions of the __fiber__ object can be
-used. __join__ will block the calling fiber until the fiber represented by the __fiber__ object has completed.
-If the fiber has already completed, or the __fiber__ object represents __not_a_fiber__, then __join__ returns
-immediately.
+ void some_fn()
+ {}
- void some_fn()
- {}
+ void joining_fiber_fn( boost::fiber f)
+ { f.join(); }
- void joining_fiber_fn( boost::fiber f)
- { f.join(); }
+ boost:.fibers::scheduler sched;
+ boost::fiber f( some_fn);
+ sched.submit_fiber( f);
+ sched.make_fiber( joining_fiber, f);
+ for (;;)
+ {
+ while ( sched.run() );
+ if ( sched.empty() ) break;
+ }
- boost:.fibers::scheduler sched;
- boost::fiber f( some_fn);
- sched.submit_fiber( f);
- sched.make_fiber( joining_fiber, f);
- for (;;)
- {
- while ( sched.run() );
- if ( sched.empty() ) break;
- }
+ [heading Interruption]
-[heading Interruption]
+ A running fiber can be ['interrupted] by invoking the __interrupt__ member function. When the interrupted fiber
+ next executes one of the specified __interruption_points__ (or if it is currently __blocked__ whilst executing one)
+ with interruption enabled, then a __fiber_interrupted__ exception will be thrown in the interrupted fiber. If not
+ caught, this will cause the execution of the interrupted fiber to terminate.
-A running fiber can be ['interrupted] by invoking the __interrupt__ member function. When the interrupted fiber
-next executes one of the specified __interruption_points__ (or if it is currently __blocked__ whilst executing one)
-with interruption enabled, then a __fiber_interrupted__ exception will be thrown in the interrupted fiber. If not
-caught, this will cause the execution of the interrupted fiber to terminate.
+ If a fiber wishes to avoid being interrupted, it can create an instance of __disable_interruption__. Objects of this
+ class disable interruption for the fiber that created them on construction, and restore the interruption state to
+ whatever it was before on destruction:
-If a fiber wishes to avoid being interrupted, it can create an instance of __disable_interruption__. Objects of this
-class disable interruption for the fiber that created them on construction, and restore the interruption state to
-whatever it was before on destruction:
+ void f()
+ {
+ // interruption enabled here
+ {
+ boost::this_fiber::disable_interruption disabler1;
+ // interruption disabled
+ {
+ boost::this_fiber::disable_interruption disabler2;
+ // interruption still disabled
+ } // disabler2 destroyed, interruption state restored
+ // interruption still disabled
+ } // disabler1 destroyed, interruption state restored
+ // interruption now enabled
+ }
- void f()
- {
- // interruption enabled here
- {
- boost::this_fiber::disable_interruption disabler1;
- // interruption disabled
- {
- boost::this_fiber::disable_interruption disabler2;
- // interruption still disabled
- } // disabler2 destroyed, interruption state restored
- // interruption still disabled
- } // disabler1 destroyed, interruption state restored
- // interruption now enabled
- }
+ The effects of an instance of __disable_interruption__ can be temporarily reversed by constructing an instance of
+ __restore_interruption__, passing in the __disable_interruption__ object in question. This will restore the
+ interruption state to what it was when the __disable_interruption__ object was constructed, and then disable
+ interruption again when the __restore_interruption__ object is destroyed.
-The effects of an instance of __disable_interruption__ can be temporarily reversed by constructing an instance of
-__restore_interruption__, passing in the __disable_interruption__ object in question. This will restore the
-interruption state to what it was when the __disable_interruption__ object was constructed, and then disable
-interruption again when the __restore_interruption__ object is destroyed.
+ void g()
+ {
+ // interruption enabled here
+ {
+ boost::this_fiber::disable_interruption disabler;
+ // interruption disabled
+ {
+ boost::this_fiber::restore_interruption restorer( disabler);
+ // interruption now enabled
+ } // restorer destroyed, interruption disable again
+ } // disabler destroyed, interruption state restored
+ // interruption now enabled
+ }
- void g()
- {
- // interruption enabled here
- {
- boost::this_fiber::disable_interruption disabler;
- // interruption disabled
- {
- boost::this_fiber::restore_interruption restorer( disabler);
- // interruption now enabled
- } // restorer destroyed, interruption disable again
- } // disabler destroyed, interruption state restored
- // interruption now enabled
- }
+ At any point, the interruption state for the current fiber can be queried by calling __interruption_enabled__.
-At any point, the interruption state for the current fiber can be queried by calling __interruption_enabled__.
+ [#interruption_points]
-[#interruption_points]
+ [heading Predefined Interruption Points]
-[heading Predefined Interruption Points]
+ The following functions are ['interruption points], which will throw __fiber_interrupted__ if interruption is
+ enabled for the current fiber, and interruption is requested for the current fiber:
-The following functions are ['interruption points], which will throw __fiber_interrupted__ if interruption is
-enabled for the current fiber, and interruption is requested for the current fiber:
+ * [join_link `boost::fiber::join()`]
+ * [cond_wait_link `boost::fibers::condition::wait()`]
+ * [auto_reset_wait_link `boost::fibers::auto_reset_event::wait()`]
+ * [manual_reset_wait_link `boost::fibers::manual_reset_event::wait()`]
+ * [count_down_wait_link `boost::fibers::count_down_event::wait()`]
+ * __interruption_point__
-* [join_link `boost::fiber::join()`]
-* [cond_wait_link `boost::fibers::condition::wait()`]
-* [auto_reset_wait_link `boost::fibers::auto_reset_event::wait()`]
-* [manual_reset_wait_link `boost::fibers::manual_reset_event::wait()`]
-* [count_down_wait_link `boost::fibers::count_down_event::wait()`]
-* __interruption_point__
+ [heading Fiber IDs]
-[heading Fiber IDs]
+ Objects of class __fiber_id__ can be used to identify fibers. Each running fiber has a unique ID
+ obtainable from the corresponding __fiber__ by calling the `get_id()` member function, or by calling
+ `boost::this_fiber::get_id()` from within the fiber. Objects of class __fiber_id__ can be copied, and used as
+ keys in associative containers: the full range of comparison operators is provided. Fiber IDs can also be written
+ to an output stream using the stream insertion operator, though the output format is unspecified.
-Objects of class __fiber_id__ can be used to identify fibers. Each running fiber has a unique ID
-obtainable from the corresponding __fiber__ by calling the `get_id()` member function, or by calling
-`boost::this_fiber::get_id()` from within the fiber. Objects of class __fiber_id__ can be copied, and used as
-keys in associative containers: the full range of comparison operators is provided. Fiber IDs can also be written
-to an output stream using the stream insertion operator, though the output format is unspecified.
+ Each instance of __fiber_id__ either refers to some fiber, or __not_a_fiber__. Instances that refer to __not_a_fiber__
+ compare equal to each other, but 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.
-Each instance of __fiber_id__ either refers to some fiber, or __not_a_fiber__. Instances that refer to __not_a_fiber__
-compare equal to each other, but 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.
+ [section:fiber Class `fiber`]
-[section:fiber Class `fiber`]
+ #include <boost/fiber/fiber.hpp>
- #include <boost/fiber/fiber.hpp>
+ class fiber
+ {
+ public:
+ fiber();
+ ~fiber();
- class fiber
- {
- public:
- fiber();
- ~fiber();
+ template< typename Fn >
+ explicit fiber( Fn fn);
- template< typename Fn >
- explicit fiber( Fn fn);
+ template< typename Fn >
+ explicit fiber( std::size_t stack_size, Fn fn);
- template< typename Fn >
- explicit fiber( std::size_t stack_size, Fn fn);
+ template< typename Fn, typename A1, typename A2,...>
+ fiber( Fn fn, A1 a1, A2 a2,...);
- template< typename Fn, typename A1, typename A2,...>
- fiber( Fn fn, A1 a1, A2 a2,...);
+ template< typename Fn, typename A1, typename A2,...>
+ fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
- template< typename Fn, typename A1, typename A2,...>
- fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ template< typename Fn >
+ fiber( detail::fiber_move_t< Fn > f);
- template< typename Fn >
- fiber( detail::fiber_move_t< Fn > f);
+ // move support
+ fiber( detail::fiber_move_t< fiber > x);
+ fiber & operator=( detail::fiber_move_t< fiber > x);
+ operator detail::fiber_move_t< fiber >();
+ detail::fiber_move_t< fiber > move();
- // move support
- fiber( detail::fiber_move_t< fiber > x);
- fiber & operator=( detail::fiber_move_t< fiber > x);
- operator detail::fiber_move_t< fiber >();
- detail::fiber_move_t< fiber > move();
+ operator unspecified-bool-type() const;
+
+ bool operator!() const;
+
+ void swap( fiber & other);
+
+ id get_id() const;
+
+ bool operator==( fiber const&) const;
+ bool operator!=( fiber const&) const;
+
+ bool is_alive() const;
+
+ int priority() const;
+
+ void priority( int);
+
+ void interrupt();
+ bool interruption_requested() const;
+
+ void cancel();
+
+ void join();
+ };
- operator ``['unspecified-bool-type]``() const;
-
- bool operator!() const;
-
- void swap( fiber & other);
-
- id get_id() const;
-
- bool operator==( fiber const&) const;
- bool operator!=( fiber const&) const;
-
- bool is_alive() const;
-
- int priority() const;
-
- void priority( int);
-
- void interrupt();
- bool interruption_requested() const;
-
- void cancel();
-
- void join();
- };
+ void swap( fiber & lhs, fiber & rhs);
- void swap( fiber & lhs, fiber & rhs);
+ template< typename Fn >
+ fiber make_fiber( Fn fn);
- template< typename Fn >
- fiber make_fiber( Fn fn);
+ template< typename Fn >
+ fiber make_fiber( std::size_t stack_size, Fn fn);
- template< typename Fn >
- fiber make_fiber( std::size_t stack_size, Fn fn);
+ template< typename Fn, typename A1, typename A2,... >
+ fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
+ template< typename Fn, typename A1, typename A2,... >
+ fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ [section:default_constructor Default Constructor]
-[section:default_constructor Default Constructor]
+ fiber();
- fiber();
+ [variablelist
+ [[Effects:] [Constructs a __fiber__ instance that refers to __not_a_fiber__.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [Constructs a __fiber__ instance that refers to __not_a_fiber__.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:callable_constructor Fiber Constructor]
-
- template< typename Callable >
- fiber( Callable fn);
-
- template< typename Callable >
- fiber( std::size_t stack_size, Callable fn);
-
-[variablelist
-[[Preconditions:] [`Callable` must by copyable.]]
-[[Effects:] [`fn` is copied into storage managed internally by the fiber library, and that copy is invoked on a
-newly-created fiber. Second version sets the stack-size of the fiber.]]
-[[Postconditions:] [`*this` refers to the newly created fiber.]]
-[[Throws:] [__system_error__ if system call failed.]]
-]
-[endsect]
-
-[section:multiple_argument_constructor Fiber Constructor with arguments]
+ [section:callable_constructor Fiber Constructor]
- template< typename Fn, typename A1, typename A2,...>
- fiber( Fn fn,A1 a1,A2 a2,...);
+ template< typename Callable >
+ fiber( Callable fn);
- template< typename Fn, typename A1, typename A2,...>
- fiber( std::size_t stack_size, Fn fn,A1 a1,A2 a2,...);
+ template< typename Callable >
+ fiber( std::size_t stack_size, Callable fn);
-[variablelist
-[[Preconditions:] [`Fn` and each `A`n must by copyable or movable.]]
-[[Effects:] [As if [link
-fiber.fiber_management.fiber.callable_constructor
-`fiber( boost::bind( fn, a1, a2,...) )`. Consequently, `fn` and each `a`n
-are copied into internal storage for access by the new fiber.
-Second version additionaly sets the stack-size used by the fiber.]]]
-[[Postconditions:] [`*this` refers to the newly created fiber.]]
-[[Throws:] [__system_error__ if system call failed.]]
-[[Note:] [Currently up to nine additional arguments `a1` to `a9` can be specified in addition to the function `fn`.]]
-]
-[endsect]
-
-[section:destructor Fiber Destructor]
+ [variablelist
+ [[Preconditions:] [`Callable` must by copyable.]]
+ [[Effects:] [`fn` is copied into storage managed internally by the fiber library, and that copy is invoked on a
+ newly-created fiber. Second version sets the stack-size of the fiber.]]
+ [[Postconditions:] [`*this` refers to the newly created fiber.]]
+ [[Throws:] [__system_error__ if system call failed.]]
+ ]
+ [endsect]
- ~fiber();
-
-[variablelist
-[[Effects:] [Destroys `*this`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:multiple_argument_constructor Fiber Constructor with arguments]
-[section:get_id Member function `get_id()`]
-
- fiber::id get_id() const;
-
-[variablelist
-[[Returns:] [If `*this` refers to a fiber, an instance of __fiber_id__ that represents that fiber. Otherwise returns
-a default-constructed __fiber_id__.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ template< typename Fn, typename A1, typename A2,...>
+ fiber( Fn fn,A1 a1,A2 a2,...);
-[section:join Member function `join()`]
+ template< typename Fn, typename A1, typename A2,...>
+ fiber( std::size_t stack_size, Fn fn,A1 a1,A2 a2,...);
- void join();
+ [variablelist
+ [[Preconditions:] [`Fn` and each `A`n must by copyable or movable.]]
+ [[Effects:] [As if [link
+ fiber.fiber_management.fiber.callable_constructor
+ `fiber( boost::bind( fn, a1, a2,...) )`. Consequently, `fn` and each `a`n
+ are copied into internal storage for access by the new fiber.
+ Second version additionaly sets the stack-size used by the fiber.]]]
+ [[Postconditions:] [`*this` refers to the newly created fiber.]]
+ [[Throws:] [__system_error__ if system call failed.]]
+ [[Note:] [Currently up to nine additional arguments `a1` to `a9` can be specified in addition to the function `fn`.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [Waits for that fiber to complete.]]
-[[Throws:] [__fiber_interrupted__ if the current fiber is interrupted and __system_error__
-if system call failed.]]
-[[Notes:] [`join()` is one of the predefined __interruption_points__.]]
-]
-[endsect]
+ [section:destructor Fiber Destructor]
-[section:interrupt Member function `interrupt()`]
+ ~fiber();
- void interrupt();
+ [variablelist
+ [[Effects:] [Destroys `*this`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [If `*this` refers to a fiber, request that the fiber will be interrupted the next time it enters one of
-the predefined __interruption_points__ with interruption enabled, or if it is currently __blocked__ in a call to one
-of the predefined __interruption_points__ with interruption enabled .]]
-[[Throws:] [__fiber_moved__ if not a fiber of execution.]]
-]
-[endsect]
+ [section:get_id Member function `get_id()`]
-[section:interruption_requested Member function `interruption_requested()`]
+ fiber::id get_id() const;
- bool interruption_requested();
+ [variablelist
+ [[Returns:] [If `*this` refers to a fiber, an instance of __fiber_id__ that represents that fiber. Otherwise returns
+ a default-constructed __fiber_id__.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [If `*this` refers to a fiber, the function returns if the interruption of the fiber was already
-requested.]]
-[[Throws:] [__fiber_moved__ if `*this` is not a fiber of execution.]]
-]
-[endsect]
+ [section:join Member function `join()`]
-[section:cancel Member function `cancel()`]
+ void join();
- void cancel();
+ [variablelist
+ [[Effects:] [Waits for that fiber to complete.]]
+ [[Throws:] [__fiber_interrupted__ if the current fiber is interrupted and __system_error__
+ if system call failed.]]
+ [[Notes:] [`join()` is one of the predefined __interruption_points__.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [If `*this` refers to a fiber, request that the fiber will be canceled the next time it yields its
-execution.]]
-[[Throws:] [__system_error__ if system call fails. __fiber__moved__ if `*this` is not a fiber of execution.]]
-]
-[endsect]
+ [section:interrupt Member function `interrupt()`]
-[section:is_alive Member function `is_alive()`]
+ void interrupt();
- bool is_alive();
+ [variablelist
+ [[Effects:] [If `*this` refers to a fiber, request that the fiber will be interrupted the next time it enters one of
+ the predefined __interruption_points__ with interruption enabled, or if it is currently __blocked__ in a call to one
+ of the predefined __interruption_points__ with interruption enabled .]]
+ [[Throws:] [__fiber_moved__ if not a fiber of execution.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [If `*this` refers to a fiber, the function returns false if the fiber is terminated or not started
-Otherwise it returns true.]]
-[[Throws:] [__fiber_moved__ if `*this` is not a fiber of execution.]]
-]
-[endsect]
+ [section:interruption_requested Member function `interruption_requested()`]
-[section:unspec_operator `operator unspecified-bool-type() const`]
+ bool interruption_requested();
- operator ``['unspecified-bool-type]``() const;
+ [variablelist
+ [[Effects:] [If `*this` refers to a fiber, the function returns if the interruption of the fiber was already
+ requested.]]
+ [[Throws:] [__fiber_moved__ if `*this` is not a fiber of execution.]]
+ ]
+ [endsect]
-[variablelist
-[[Returns:] [If `*this` refers to a fiber, the function returns true. Otherwise false.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:cancel Member function `cancel()`]
-[section:not_operator `operator!`]
+ void cancel();
- bool operator!() const;
+ [variablelist
+ [[Effects:] [If `*this` refers to a fiber, request that the fiber will be canceled the next time it yields its
+ execution.]]
+ [[Throws:] [__system_error__ if system call fails. __fiber__moved__ if `*this` is not a fiber of execution.]]
+ ]
+ [endsect]
-[variablelist
-[[Returns:] [If `*this` refers not to a fiber, the function returns true. Otherwise false.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:is_alive Member function `is_alive()`]
-[section:equals `operator==`]
+ bool is_alive();
- bool operator==(const fiber& other) const;
+ [variablelist
+ [[Effects:] [If `*this` refers to a fiber, the function returns false if the fiber is terminated or not started
+ Otherwise it returns true.]]
+ [[Throws:] [__fiber_moved__ if `*this` is not a fiber of execution.]]
+ ]
+ [endsect]
-[variablelist
-[[Returns:] [`get_id()==other.get_id()`]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:unspec_operator `operator unspecified-bool-type() const`]
-[section:not_equals `operator!=`]
+ operator unspecified-bool-type() const;
- bool operator!=(const fiber& other) const;
+ [variablelist
+ [[Returns:] [If `*this` refers to a fiber, the function returns true. Otherwise false.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
-[variablelist
-[[Returns:] [`get_id()!=other.get_id()`]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:not_operator `operator!`]
-[section:swap Member function `swap()`]
+ bool operator!() const;
- void swap(fiber& other);
+ [variablelist
+ [[Returns:] [If `*this` refers not to a fiber, the function returns true. Otherwise false.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
-[variablelist
-[[Effects:] [Exchanges the fibers associated with `*this` and `other`, so `*this` is associated with the fiber
-associated with `other` prior to the call, and vice-versa.]]
-[[Postconditions:] [`this->get_id()` returns the same value as `other.get_id()` prior to the call. `other.get_id()`
-returns the same value as `this->get_id()` prior to the call.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ [section:equals `operator==`]
-[section:non_member_swap Non-member function `swap()`]
+ bool operator==(const fiber& other) const;
- #include <boost/fiber/fiber.hpp>
+ [variablelist
+ [[Returns:] [`get_id()==other.get_id()`]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
- void swap( fiber & lhs, fiber & rhs);
+ [section:not_equals `operator!=`]
-[variablelist
-[[Effects:] [[link fiber.fiber_management.fiber.swap `lhs.swap( rhs)`].]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ bool operator!=(const fiber& other) const;
-[section:non_member_make_fiber Non-member template function `make_fiber()`]
+ [variablelist
+ [[Returns:] [`get_id()!=other.get_id()`]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
- #include <boost/fiber/fiber.hpp>
+ [section:swap Member function `swap()`]
- template< typename Fn >
- fiber make_fiber( Fn fn);
+ void swap(fiber& other);
- template< typename Fn >
- fiber make_fiber( std::size_t stack_size, Fn fn);
+ [variablelist
+ [[Effects:] [Exchanges the fibers associated with `*this` and `other`, so `*this` is associated with the fiber
+ associated with `other` prior to the call, and vice-versa.]]
+ [[Postconditions:] [`this->get_id()` returns the same value as `other.get_id()` prior to the call. `other.get_id()`
+ returns the same value as `this->get_id()` prior to the call.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
+ [section:non_member_swap Non-member function `swap()`]
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ #include <boost/fiber/fiber.hpp>
-[variablelist
-[[Effects:] [Creates a fiber.]]
-]
-[endsect]
+ void swap( fiber & lhs, fiber & rhs);
-[section:id Class `boost::fiber::id`]
+ [variablelist
+ [[Effects:] [[link fiber.fiber_management.fiber.swap `lhs.swap( rhs)`].]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
- #include <boost/fiber/fiber.hpp>
+ [section:non_member_make_fiber Non-member template function `make_fiber()`]
- class fiber::id
- {
- public:
- id();
-
- bool operator==( id const& x) const;
- bool operator!=( id const& x) const;
- bool operator<( id const& x) const;
- bool operator>( id const& x) const;
- bool operator<=( id const& x) const;
- bool operator>=( id const& x) const;
-
- template< typename charT, typename traitsT >
- friend std::basic_ostream< charT, traitsT > &
- operator<<( std::basic_ostream< charT, traitsT > & os, id const& x);
- };
-
-[section:constructor Default constructor]
-
- id();
-
-[variablelist
-[[Effects:] [Constructs a __fiber_id__ instance that represents __not_a_fiber__.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ #include <boost/fiber/fiber.hpp>
-[section:is_equal `operator==`]
+ template< typename Fn >
+ fiber make_fiber( Fn fn);
- bool operator==( id const& x) const;
+ template< typename Fn >
+ fiber make_fiber( std::size_t stack_size, Fn fn);
-[variablelist
-[[Returns:] [`true` if `*this` and `x` both represent the same fiber, or both represent __not_a_fiber__, `false`
-otherwise.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ template< typename Fn, typename A1, typename A2,... >
+ fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
-[section:not_equal `operator!=`]
-
- bool operator!=( id const& x) const;
-
-[variablelist
-[[Returns:] [`true` if `*this` and `x` represent different fibers, or one represents a fiber, and
-the other represent __not_a_fiber__, `false` otherwise.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:less_than `operator<`]
-
- bool operator<( id const& x) const;
-
-[variablelist
-[[Returns:] [`true` if `*this!=x` is `true` and the implementation-defined total order of __fiber_id__ values places
-`*this` before `y`, `false` otherwise.]]
-[[Throws:] [Nothing.]]
-[[Note:] [A __fiber_id__ instance representing __not_a_fiber__ will always compare less than an instance representing
-a fiber of execution.]]
-]
-[endsect]
-
-
-[section:greater_than `operator>`]
-
- bool operator>( id const& x) const;
-
-[variablelist
-[[Returns:] [`x<*this`]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:less_than_or_equal `operator>=`]
-
- bool operator<=( id const& x) const;
-
-[variablelist
-[[Returns:] [`!(x<*this)`]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:greater_than_or_equal `operator>=`]
-
- bool operator>=( id const& x) const;
-
-[variablelist
-[[Returns:] [`!(*this<x)`]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:stream_out Friend `operator<<`]
-
- template< typename charT, typename traitsT >
- friend std::basic_ostream< charT, traitsT > &
- operator<<( std::basic_ostream< charT, traitsT > & os, id const& x);
-
-[variablelist
-[[Effects:] [Writes a representation of the __fiber_id__ instance `x` to the stream `os`, such that the representation of two
-instances of __fiber_id__ `a` and `b` is the same if `a==b`, and different if `a!=b`.]]
-[[Returns:] [`os`]]
-]
-[endsect]
-
-[endsect]
-
-[endsect]
+ template< typename Fn, typename A1, typename A2,... >
+ fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ [variablelist
+ [[Effects:] [Creates a fiber.]]
+ ]
+ [endsect]
-[section:this_fiber Namespace `this_fiber`]
-
-[section:runs_as_fiber Non-member function `runs_as_fiber()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- bool runs_as_fiber();
- }
-
-[variablelist
-[[Returns:] [Returns `true` if current execution context is a fiber.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:get_id Non-member function `get_id()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- fiber::id get_id();
- }
-
-[variablelist
-[[Returns:] [An instance of __fiber_id__ that represents that currently executing fiber.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:interruption_point Non-member function `interruption_point()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- void interruption_point();
- }
-
-[variablelist
-[[Effects:] [Check to see if the current fiber has been interrupted.]]
-[[Throws:] [__fiber_interrupted__ if __interruption_enabled__ and __interruption_requested__ both return `true` and
-__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:interruption_requested Non-member function `interruption_requested()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- bool interruption_requested();
- }
-
-[variablelist
-[[Returns:] [`true` if interruption has been requested for the current fiber, `false` otherwise.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:interruption_enabled Non-member function `interruption_enabled()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- bool interruption_enabled();
- }
-
-[variablelist
-[[Returns:] [`true` if interruption has been enabled for the current fiber, `false` otherwise.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:yield Non-member function `yield()`]
-
- #include <boost/fiber/utility.hppV>
-
- namespace this_fiber
- {
- void yield();
- }
-
-[variablelist
-[[Effects:] [Cooperativly allows other fibers to run.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:cancel Non-member function `cancel()`]
-
- #include <boost/fiber/utility.hpp>
-
- namespace this_fiber
- {
- void cancel();
- }
-
-[variablelist
-[[Effects:] [Fiber gets canceled after calling `yield`.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:disable_interruption Class `disable_interruption`]
-
- #include <boost/fiber/interruption.hpp>
-
- namespace this_fiber
- {
- class disable_interruption
- {
- public:
- disable_interruption();
- ~disable_interruption();
- };
- }
-
-`boost::this_fiber::disable_interruption` disables interruption for the current fiber on construction, and restores
-the prior interruption state on destruction. Instances of `disable_interruption` cannot be copied or moved.
-
-[section:constructor Constructor]
-
- disable_interruption();
-
-[variablelist
-[[Effects:] [Stores the current state of __interruption_enabled__ and disables interruption for the current fiber.]]
-[[Postconditions:] [__interruption_enabled__ returns `false` for the current fiber.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:destructor Destructor]
-
- ~disable_interruption();
-
-[variablelist
-[[Preconditions:] [Must be called from the same fiber from which `*this` was constructed.]]
-[[Effects:] [Restores the current state of __interruption_enabled__ for the current fiber to that prior to the
-construction of `*this`.]]
-[[Postconditions:] [__interruption_enabled__ for the current fiber returns the value stored in the constructor of
-`*this`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[endsect]
-
-[section:restore_interruption Class `restore_interruption`]
-
- #include <boost/fiber/interruption.hpp>
-
- namespace this_fiber
- {
- class restore_interruption
- {
- public:
- explicit restore_interruption( disable_interruption & disabler);
- ~restore_interruption();
- };
- }
-
-On construction of an instance of `boost::this_fiber::restore_interruption`, the interruption state for the current
-fiber is restored to the interruption state stored by the constructor of the supplied instance of
-__disable_interruption__. When the instance is destroyed, interruption is again disabled. Instances of
-`restore_interruption` cannot be copied or moved.
-
-[section:constructor Constructor]
-
- explicit restore_interruption( disable_interruption & disabler);
-
-[variablelist
-[[Preconditions:] [Must be called from the same fiber from which `disabler` was constructed.]]
-[[Effects:] [Restores the current state of __interruption_enabled__ for the current fiber to that prior to the
-construction of `disabler`.]]
-[[Postconditions:] [__interruption_enabled__ for the current fiber returns the value stored in the constructor of
-`disabler`.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
-
-[section:destructor Destructor]
-
- ~restore_interruption();
-
-[variablelist
-[[Preconditions:] [Must be called from the same fiber from which `*this` was constructed.]]
-[[Effects:] [Disables interruption for the current fiber.]]
-[[Postconditions:] [__interruption_enabled__ for the current fiber returns `false`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[endsect]
-
-[section:atfiberexit Non-member function template `at_fiber_exit()`]
-
- #include <boost/fiber/utility.hpp>
-
- template< typename Callable >
- void at_fiber_exit( Callable ca);
-
-[variablelist
-[[Effects:] [A copy of `ca`. This copy is invoked when the current fiber exits (even if the fiber has been
-interrupted).]]
-[[Postconditions:] [A copy of `ca` has been saved for invocation on fiber exit.]]
-[[Throws:] [__fiber_error__ if the execution context is not a fiber.]]
-]
-[endsect]
+ [endsect]
[endsect]
Modified: sandbox/fiber/libs/fiber/doc/lockables.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/lockables.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/lockables.qbk 2009-11-20 20:29:57 EST (Fri, 20 Nov 2009)
@@ -7,274 +7,278 @@
[section:mutex_concepts Mutex Concepts]
-A mutex object facilitates protection against data races and allows synchronization of data between fibers. A fiber
-obtains ownership of a mutex object by calling one of the lock functions and relinquishes ownership by calling the
-corresponding unlock function.
-
-__boost_fiber__ supports one basic concept for lockable objects: __lockable_concept_type__.
-
-[section:lockable `Lockable` Concept]
-
-The __lockable_concept__ models exclusive ownership. A type that implements the __lockable_concept__ shall provide
-the following member functions:
-
-* [lock_ref_link `void lock();`]
-* [try_lock_ref_link `bool try_lock();`]
-* [unlock_ref_link `void unlock();`]
-
-Lock ownership acquired through a call to __lock_ref__ or __try_lock_ref__ must be released through a call to
-__unlock_ref__.
-
-[section:lock `void lock()`]
-[variablelist
-[[Effects:] [The current fiber blocks until ownership can be obtained for the current fiber.]]
-[[Postcondition:] [The current fiber owns `*this`.]]
-[[Throws:] [__lock_error__ if an error occurs.]]
-]
-[endsect]
-
-[section:try_lock `bool try_lock()`]
-[variablelist
-[[Effects:] [Attempt to obtain ownership for the current fiber without blocking.]]
-[[Returns:] [`true` if ownership was obtained for the current fiber, `false` otherwise.]]
-[[Postcondition:] [If the call returns `true`, the current fiber owns the `*this`.]]
-[[Throws:] [__lock_error__ if an error occurs.]]
-]
-[endsect]
-
-[section:unlock `void unlock()`]
-[variablelist
-[[Precondition:] [The current fiber owns `*this`.]]
-[[Effects:] [Releases ownership by the current fiber.]]
-[[Postcondition:] [The current fiber no longer owns `*this`.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:locks Lock Types]
-
-[section:lock_guard Class template `lock_guard`]
-
- #include <boost/fiber/locks.hpp>
-
- template< typename Lockable >
- class lock_guard
- {
- public:
- explicit lock_guard( Lockable & m_);
- lock_guard( Lockable & m_, boost::adopt_lock_t);
-
- ~lock_guard();
- };
-
-__lock_guard__ is very simple: on construction it
-acquires ownership of the implementation of the __lockable_concept__ supplied as
-the constructor parameter. On destruction, the ownership is released. This
-provides simple RAII-style locking of a __lockable_concept_type__ object, to facilitate exception-safe
-locking and unlocking. In addition, the [link
-fiber.synchronization.locks.lock_guard.constructor_adopt `lock_guard( Lockable &
-m, boost::adopt_lock_t)` constructor] allows the __lock_guard__ object to
-take ownership of a lock already held by the current fiber.
-
-[section:constructor `lock_guard( Lockable & m)`]
-[variablelist
-[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]
-[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]
-]
-[endsect]
-
-[section:constructor_adopt `lock_guard( Lockable & m, boost::adopt_lock_t)`]
-[variablelist
-[[Precondition:] [The current fiber owns a lock on `m` equivalent to one
-obtained by a call to [lock_ref_link `m.lock()`].]]
-[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of
-`m`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:destructor `~lock_guard()`]
-[variablelist
-[[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__
-object passed to the constructor.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:unique_lock Class template `unique_lock`]
-
- #include <boost/fiber/locks.hpp>
-
- template< typename Lockable >
- class unique_lock
- {
- public:
- unique_lock();
- explicit unique_lock( Lockable & m_);
- unique_lock( Lockable & m_, adopt_lock_t);
- unique_lock( Lockable & m_, defer_lock_t);
- unique_lock( Lockable & m_, try_to_lock_t);
- unique_lock( Lockable & m_, system_time const& target_time);
-
- ~unique_lock();
-
- unique_lock( detail::fiber_move_t< unique_lock< Lockable > > other);
- unique_lock( detail::fiber_move_t< upgrade_lock< Lockable > > other);
-
- operator detail::fiber_move_t< unique_lock< Lockable > >();
- detail::fiber_move_t< unique_lock< Lockable > > move();
- unique_lock& operator=( detail::fiber_move_t< unique_lock< Lockable > > other);
- unique_lock& operator=( detail::fiber_move_t< upgrade_lock< Lockable > > other);
-
- void swap( unique_lock & other);
- void swap( detail::fiber_move_t< unique_lock< Lockable > > other);
-
- void lock();
- bool try_lock();
-
- void unlock();
-
- bool owns_lock() const;
- operator ``['unspecified-bool-type]``() const;
- bool operator!() const;
-
- Lockable * mutex() const;
- Lockable * release();
- };
-
-__unique_lock__ is more complex than __lock_guard__: not only does it provide for RAII-style locking, it also allows
-for deferring acquiring the lock until the __lock_ref__ member function is called explicitly, or trying to acquire
-the lock in a non-blocking fashion, or with a timeout. Consequently, __unlock_ref__ is only called in the destructor
-if the lock object has locked the __lockable_concept_type__ object, or otherwise adopted a lock on the
-__lockable_concept_type__ object.
-
-Specializations of __unique_lock__ model the __timed_lockable_concept__ if the supplied __lockable_concept_type__
-type itself models __timed_lockable_concept__ (e.g. `boost::unique_lock<boost::timed_mutex>`), or the
-__lockable_concept__ otherwise (e.g. `boost::unique_lock<boost::mutex>`).
-
-An instance of __unique_lock__ is said to ['own] the lock state of a __lockable_concept_type__ `m` if
-__mutex_func_ref__ returns a pointer to `m` and __owns_lock_ref__ returns `true`. If an object that ['owns] the lock
-state of a __lockable_concept_type__ object is destroyed, then the destructor will invoke [unlock_ref_link
-`mutex()->unlock()`].
-
-The member functions of __unique_lock__ are not fiber-safe. In particular, __unique_lock__ is intended to model the
-ownership of a __lockable_concept_type__ object by a particular fiber, and the member functions that release
-ownership of the lock state (including the destructor) must be called by the same fiber that acquired ownership of
-the lock state.
-
-[section:defaultconstructor `unique_lock()`]
-
-[variablelist
-[[Effects:] [Creates a lock object with no associated mutex.]]
-[[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `NULL`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:constructor `unique_lock(Lockable & m)`]
-
-[variablelist
-[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]
-[[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]
-[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]
-]
-[endsect]
-
-[section:constructor_adopt `unique_lock(Lockable & m,boost::adopt_lock_t)`]
-
-[variablelist
-[[Precondition:] [The current fiber owns an exclusive lock on `m`.]]
-[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of `m`.]]
-[[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:constructor_defer `unique_lock(Lockable & m,boost::defer_lock_t)`]
-
-[variablelist
-[[Effects:] [Stores a reference to `m`.]]
-[[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `&m`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:constructor_try `unique_lock(Lockable & m,boost::try_to_lock_t)`]
-
-[variablelist
-[[Effects:] [Stores a reference to `m`. Invokes [try_lock_ref_link
-`m.try_lock()`], and takes ownership of the lock state if the call returns
-`true`.]]
-[[Postcondition:] [__mutex_func_ref__ returns `&m`. If the call to __try_lock_ref__
-returned `true`, then __owns_lock_ref__ returns `true`, otherwise __owns_lock_ref__
-returns `false`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:destructor `~unique_lock()`]
-
-[variablelist
-[[Effects:] [Invokes __mutex_func_ref__`->`[unlock_ref_link `unlock()`] if
-__owns_lock_ref__ returns `true`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
+ A mutex object facilitates protection against data races and allows synchronization of data between fibers. A fiber
+ obtains ownership of a mutex object by calling one of the lock functions and relinquishes ownership by calling the
+ corresponding unlock function.
+
+ __boost_fiber__ supports one basic concept for lockable objects: __lockable_concept_type__.
+
+ [section:lockable `Lockable` Concept]
+
+ The __lockable_concept__ models exclusive ownership. A type that implements the __lockable_concept__ shall provide
+ the following member functions:
+
+ * [lock_ref_link `void lock();`]
+ * [try_lock_ref_link `bool try_lock();`]
+ * [unlock_ref_link `void unlock();`]
+
+ Lock ownership acquired through a call to __lock_ref__ or __try_lock_ref__ must be released through a call to
+ __unlock_ref__.
+
+ [section:lock `void lock()`]
+ [variablelist
+ [[Effects:] [The current fiber blocks until ownership can be obtained for the current fiber.]]
+ [[Postcondition:] [The current fiber owns `*this`.]]
+ [[Throws:] [__lock_error__ if an error occurs.]]
+ ]
+ [endsect]
+
+ [section:try_lock `bool try_lock()`]
+ [variablelist
+ [[Effects:] [Attempt to obtain ownership for the current fiber without blocking.]]
+ [[Returns:] [`true` if ownership was obtained for the current fiber, `false` otherwise.]]
+ [[Postcondition:] [If the call returns `true`, the current fiber owns the `*this`.]]
+ [[Throws:] [__lock_error__ if an error occurs.]]
+ ]
+ [endsect]
+
+ [section:unlock `void unlock()`]
+ [variablelist
+ [[Precondition:] [The current fiber owns `*this`.]]
+ [[Effects:] [Releases ownership by the current fiber.]]
+ [[Postcondition:] [The current fiber no longer owns `*this`.]]
+ [[Throws:] [Nothing]]
+ ]
+ [endsect]
+
+ [endsect]
+
+
+ [section:locks Lock Types]
+
+ [section:lock_guard Class template `lock_guard`]
+
+ #include <boost/fiber/locks.hpp>
+
+ template< typename Lockable >
+ class lock_guard
+ {
+ public:
+ explicit lock_guard( Lockable & m_);
+ lock_guard( Lockable & m_, boost::adopt_lock_t);
+
+ ~lock_guard();
+ };
+
+ __lock_guard__ is very simple: on construction it
+ acquires ownership of the implementation of the __lockable_concept__ supplied as
+ the constructor parameter. On destruction, the ownership is released. This
+ provides simple RAII-style locking of a __lockable_concept_type__ object, to facilitate exception-safe
+ locking and unlocking. In addition, the [link
+ fiber.synchronization.locks.lock_guard.constructor_adopt `lock_guard( Lockable &
+ m, boost::adopt_lock_t)` constructor] allows the __lock_guard__ object to
+ take ownership of a lock already held by the current fiber.
+
+ [section:constructor `lock_guard( Lockable & m)`]
+ [variablelist
+ [[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]
+ [[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]
+ ]
+ [endsect]
+
+ [section:constructor_adopt `lock_guard( Lockable & m, boost::adopt_lock_t)`]
+ [variablelist
+ [[Precondition:] [The current fiber owns a lock on `m` equivalent to one
+ obtained by a call to [lock_ref_link `m.lock()`].]]
+ [[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of
+ `m`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:destructor `~lock_guard()`]
+ [variablelist
+ [[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__
+ object passed to the constructor.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [endsect]
+
+
+ [section:unique_lock Class template `unique_lock`]
+
+ #include <boost/fiber/locks.hpp>
+
+ template< typename Lockable >
+ class unique_lock
+ {
+ public:
+ unique_lock();
+ explicit unique_lock( Lockable & m_);
+ unique_lock( Lockable & m_, adopt_lock_t);
+ unique_lock( Lockable & m_, defer_lock_t);
+ unique_lock( Lockable & m_, try_to_lock_t);
+ unique_lock( Lockable & m_, system_time const& target_time);
+
+ ~unique_lock();
+
+ unique_lock( detail::fiber_move_t< unique_lock< Lockable > > other);
+ unique_lock( detail::fiber_move_t< upgrade_lock< Lockable > > other);
+
+ operator detail::fiber_move_t< unique_lock< Lockable > >();
+ detail::fiber_move_t< unique_lock< Lockable > > move();
+ unique_lock& operator=( detail::fiber_move_t< unique_lock< Lockable > > other);
+ unique_lock& operator=( detail::fiber_move_t< upgrade_lock< Lockable > > other);
+
+ void swap( unique_lock & other);
+ void swap( detail::fiber_move_t< unique_lock< Lockable > > other);
+
+ void lock();
+ bool try_lock();
+
+ void unlock();
+
+ bool owns_lock() const;
+ operator unspecified-bool-type() const;
+ bool operator!() const;
+
+ Lockable * mutex() const;
+ Lockable * release();
+ };
+
+ __unique_lock__ is more complex than __lock_guard__: not only does it provide for RAII-style locking, it also allows
+ for deferring acquiring the lock until the __lock_ref__ member function is called explicitly, or trying to acquire
+ the lock in a non-blocking fashion, or with a timeout. Consequently, __unlock_ref__ is only called in the destructor
+ if the lock object has locked the __lockable_concept_type__ object, or otherwise adopted a lock on the
+ __lockable_concept_type__ object.
+
+ Specializations of __unique_lock__ model the __timed_lockable_concept__ if the supplied __lockable_concept_type__
+ type itself models __timed_lockable_concept__ (e.g. `boost::unique_lock<boost::timed_mutex>`), or the
+ __lockable_concept__ otherwise (e.g. `boost::unique_lock<boost::mutex>`).
+
+ An instance of __unique_lock__ is said to ['own] the lock state of a __lockable_concept_type__ `m` if
+ __mutex_func_ref__ returns a pointer to `m` and __owns_lock_ref__ returns `true`. If an object that ['owns] the lock
+ state of a __lockable_concept_type__ object is destroyed, then the destructor will invoke [unlock_ref_link
+ `mutex()->unlock()`].
+
+ The member functions of __unique_lock__ are not fiber-safe. In particular, __unique_lock__ is intended to model the
+ ownership of a __lockable_concept_type__ object by a particular fiber, and the member functions that release
+ ownership of the lock state (including the destructor) must be called by the same fiber that acquired ownership of
+ the lock state.
+
+ [section:defaultconstructor `unique_lock()`]
+
+ [variablelist
+ [[Effects:] [Creates a lock object with no associated mutex.]]
+ [[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `NULL`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:constructor `unique_lock(Lockable & m)`]
+
+ [variablelist
+ [[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]
+ [[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]
+ [[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]
+ ]
+ [endsect]
+
+ [section:constructor_adopt `unique_lock(Lockable & m,boost::adopt_lock_t)`]
+
+ [variablelist
+ [[Precondition:] [The current fiber owns an exclusive lock on `m`.]]
+ [[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of `m`.]]
+ [[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:constructor_defer `unique_lock(Lockable & m,boost::defer_lock_t)`]
+
+ [variablelist
+ [[Effects:] [Stores a reference to `m`.]]
+ [[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `&m`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:constructor_try `unique_lock(Lockable & m,boost::try_to_lock_t)`]
+
+ [variablelist
+ [[Effects:] [Stores a reference to `m`. Invokes [try_lock_ref_link
+ `m.try_lock()`], and takes ownership of the lock state if the call returns
+ `true`.]]
+ [[Postcondition:] [__mutex_func_ref__ returns `&m`. If the call to __try_lock_ref__
+ returned `true`, then __owns_lock_ref__ returns `true`, otherwise __owns_lock_ref__
+ returns `false`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:destructor `~unique_lock()`]
+
+ [variablelist
+ [[Effects:] [Invokes __mutex_func_ref__`->`[unlock_ref_link `unlock()`] if
+ __owns_lock_ref__ returns `true`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:owns_lock `bool owns_lock() const`]
+
+ [variablelist
+ [[Returns:] [`true` if the `*this` owns the lock on the __lockable_concept_type__
+ object associated with `*this`.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:mutex `Lockable* mutex() const`]
+
+ [variablelist
+ [[Returns:] [A pointer to the __lockable_concept_type__ object associated with
+ `*this`, or `NULL` if there is no such object.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:bool_conversion `operator unspecified-bool-type() const`]
+
+ [variablelist
+ [[Returns:] [If __owns_lock_ref__ would return `true`, a value that evaluates to
+ `true` in boolean contexts, otherwise a value that evaluates to `false` in
+ boolean contexts.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:operator_not `bool operator!() const`]
+
+ [variablelist
+ [[Returns:] [`!` __owns_lock_ref__.]]
+ [[Throws:] [Nothing.]]
+ ]
+ [endsect]
+
+ [section:release `Lockable* release()`]
+
+ [variablelist
+ [[Effects:] [The association between `*this` and the __lockable_concept_type__ object is removed, without affecting
+ the lock state of the __lockable_concept_type__ object. If __owns_lock_ref__ would have returned `true`, it is the
+ responsibility of the calling code to ensure that the __lockable_concept_type__ is correctly unlocked.]]
+ [[Returns:] [A pointer to the __lockable_concept_type__ object associated with `*this` at the point of the call, or
+ `NULL` if there is no such object.]]
+ [[Throws:] [Nothing.]]
+ [[Postcondition:] [`*this` is no longer associated with any __lockable_concept_type__ object. __mutex_func_ref__
+ returns `NULL` and __owns_lock_ref__ returns `false`.]]
+ ]
+ [endsect]
-[section:owns_lock `bool owns_lock() const`]
+ [endsect]
-[variablelist
-[[Returns:] [`true` if the `*this` owns the lock on the __lockable_concept_type__
-object associated with `*this`.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:mutex `Lockable* mutex() const`]
-
-[variablelist
-[[Returns:] [A pointer to the __lockable_concept_type__ object associated with
-`*this`, or `NULL` if there is no such object.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:bool_conversion `operator unspecified-bool-type() const`]
-
-[variablelist
-[[Returns:] [If __owns_lock_ref__ would return `true`, a value that evaluates to
-`true` in boolean contexts, otherwise a value that evaluates to `false` in
-boolean contexts.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:operator_not `bool operator!() const`]
-
-[variablelist
-[[Returns:] [`!` __owns_lock_ref__.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:release `Lockable* release()`]
-
-[variablelist
-[[Effects:] [The association between `*this` and the __lockable_concept_type__ object is removed, without affecting
-the lock state of the __lockable_concept_type__ object. If __owns_lock_ref__ would have returned `true`, it is the
-responsibility of the calling code to ensure that the __lockable_concept_type__ is correctly unlocked.]]
-[[Returns:] [A pointer to the __lockable_concept_type__ object associated with `*this` at the point of the call, or
-`NULL` if there is no such object.]]
-[[Throws:] [Nothing.]]
-[[Postcondition:] [`*this` is no longer associated with any __lockable_concept_type__ object. __mutex_func_ref__
-returns `NULL` and __owns_lock_ref__ returns `false`.]]
-]
-[endsect]
+ [endsect]
[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk