|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r57841 - in sandbox/fiber: . libs/fiber/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-11-21 16:43:41
Author: olli
Date: 2009-11-21 16:43:40 EST (Sat, 21 Nov 2009)
New Revision: 57841
URL: http://svn.boost.org/trac/boost/changeset/57841
Log:
- documetnation corrected
Added:
sandbox/fiber/change.log (contents, props changed)
Removed:
sandbox/fiber/libs/fiber/doc/scheduler.qbk
Text files modified:
sandbox/fiber/libs/fiber/doc/fiber.qbk | 5
sandbox/fiber/libs/fiber/doc/fiber_ref.qbk | 1104 +++++++++++++++++++++++++++------------
sandbox/fiber/libs/fiber/doc/lockables.qbk | 541 +++++++++---------
sandbox/fiber/libs/fiber/doc/todo.qbk | 2
4 files changed, 1040 insertions(+), 612 deletions(-)
Added: sandbox/fiber/change.log
==============================================================================
--- (empty file)
+++ sandbox/fiber/change.log 2009-11-21 16:43:40 EST (Sat, 21 Nov 2009)
@@ -0,0 +1,8 @@
+0.1.1 :
+-------
+- refactor STATE macros -> don't test and set only one bit
+- documentation corrected
+
+0.1.0 :
+-------
+- initial version
Modified: sandbox/fiber/libs/fiber/doc/fiber.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/fiber.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/fiber.qbk 2009-11-21 16:43:40 EST (Sat, 21 Nov 2009)
@@ -38,7 +38,7 @@
[template mutex_func_ref_link[link_text] [link fiber.synchronization.locks.unique_lock.mutex [link_text]]]
[template unique_lock_link[link_text] [link fiber.synchronization.locks.unique_lock [link_text]]]
[template join_link[link_text] [link fiber.fiber_management.fiber.join [link_text]]]
-[template cond_wait_link[link_text] [link fiber.synchronization.condvar_ref.condition_variable.wait [link_text]]]
+[template cond_wait_link[link_text] [link fiber.synchronization.condvar_ref.condition.wait [link_text]]]
[template cond_any_wait_link[link_text] [link fiber.synchronization.condvar_ref.condition_variable_any.wait [link_text]]]
@@ -79,13 +79,12 @@
[include overview.qbk]
[include fiber_ref.qbk]
-[include scheduler.qbk]
[section:synchronization Synchronization]
[include lockables.qbk]
[include mutexes.qbk]
[include condition_variables.qbk]
[include event_variables.qbk]
[include fifos.qbk]
-[include todo.qbk]
[endsect]
+[include todo.qbk]
[include acknowledgements.qbk]
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-21 16:43:40 EST (Sat, 21 Nov 2009)
@@ -7,461 +7,891 @@
[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__).
+[warning Don't use sjlj exception model.]
- [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()
+ void f()
+ {
+ // interruption enabled here
{
- // interruption enabled here
+ boost::this_fiber::disable_interruption disabler1;
+ // interruption disabled
{
- boost::this_fiber::disable_interruption disabler1;
- // interruption disabled
- {
- boost::this_fiber::disable_interruption disabler2;
- // interruption still disabled
- } // disabler2 destroyed, interruption state restored
+ boost::this_fiber::disable_interruption disabler2;
// 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.
-
- void g()
+ } // 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.
+
+ void g()
+ {
+ // interruption enabled here
{
- // interruption enabled here
+ boost::this_fiber::disable_interruption disabler;
+ // interruption disabled
{
- 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
- }
+ 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();
-
- template< typename Fn >
- explicit fiber( 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( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
-
- 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();
-
- 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();
- };
+ class fiber
+ {
+ public:
+ fiber();
+ ~fiber();
- void swap( fiber & lhs, fiber & rhs);
+ template< typename Fn >
+ explicit fiber( Fn fn);
template< typename Fn >
- fiber make_fiber( Fn 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( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
template< typename Fn >
- fiber make_fiber( std::size_t stack_size, Fn fn);
+ fiber( detail::fiber_move_t< Fn > f);
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
+ // 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();
+ };
+
+ void swap( fiber & lhs, fiber & rhs);
+
+ template< typename Fn >
+ fiber make_fiber( 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( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+
+
+[section:default_constructor Default Constructor]
+
+ fiber();
+
+[variablelist
+[[Effects:] [Constructs a __fiber__ instance that refers to __not_a_fiber__.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+[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]
+
+ 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,...);
+
+[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]
+
+ ~fiber();
+
+[variablelist
+[[Effects:] [Destroys `*this`.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[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]
+
+[section:join Member function `join()`]
+
+ void join();
+
+[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:interrupt Member function `interrupt()`]
+
+ void interrupt();
+
+[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:interruption_requested Member function `interruption_requested()`]
+
+ bool interruption_requested();
+
+[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:cancel Member function `cancel()`]
+
+ void cancel();
+
+[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:is_alive Member function `is_alive()`]
+
+ bool is_alive();
+
+[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:unspec_operator `operator unspecified-bool-type() const`]
+
+ operator unspecified-bool-type() const;
+
+[variablelist
+[[Returns:] [If `*this` refers to a fiber, the function returns true. Otherwise false.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:not_operator `operator!`]
+
+ bool operator!() const;
+
+[variablelist
+[[Returns:] [If `*this` refers not to a fiber, the function returns true. Otherwise false.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:equals `operator==`]
+
+ bool operator==(const fiber& other) const;
+
+[variablelist
+[[Returns:] [`get_id()==other.get_id()`]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:not_equals `operator!=`]
+
+ bool operator!=(const fiber& other) const;
+
+[variablelist
+[[Returns:] [`get_id()!=other.get_id()`]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:swap Member function `swap()`]
+
+ void swap(fiber& other);
+
+[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:non_member_swap Non-member function `swap()`]
+
+ #include <boost/fiber/fiber.hpp>
+
+ void swap( fiber & lhs, fiber & rhs);
+
+[variablelist
+[[Effects:] [[link fiber.fiber_management.fiber.swap `lhs.swap( rhs)`].]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:non_member_make_fiber Non-member template function `make_fiber()`]
+
+ #include <boost/fiber/fiber.hpp>
+
+ template< typename Fn >
+ fiber make_fiber( 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( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+
+[variablelist
+[[Effects:] [Creates a fiber.]]
+]
+[endsect]
+
+[section:id Class `boost::fiber::id`]
+
+ #include <boost/fiber/fiber.hpp>
+ class fiber::id
+ {
+ public:
+ id();
+
+ bool operator==(const id& y) const;
+ bool operator!=(const id& y) const;
+ bool operator<(const id& y) const;
+ bool operator>(const id& y) const;
+ bool operator<=(const id& y) const;
+ bool operator>=(const id& y) const;
+
+ template<class charT, class traits>
+ friend std::basic_ostream<charT, traits>&
+ operator<<(std::basic_ostream<charT, traits>& os, const id& x);
+ };
+
+[section:constructor Default constructor]
+
+ id();
+
+[variablelist
+[[Effects:] [Constructs a __fiber_id__ instance that represents __not_a_fiber__.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[section:is_equal `operator==`]
+
+ bool operator==(const id& y) const;
+
+[variablelist
+[[Returns:] [`true` if `*this` and `y` both represent the same fiber of execution, or both represent __not_a_fiber__, `false`
+otherwise.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[section:not_equal `operator!=`]
+
+ bool operator!=(const id& y) const;
+
+[variablelist
+[[Returns:] [`true` if `*this` and `y` represent different fibers of execution, or one represents a fiber of execution, and
+the other represent __not_a_fiber__, `false` otherwise.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[section:less_than `operator<`]
+
+ bool operator<(const id& y) const;
+
+[variablelist
+[[Returns:] [`true` if `*this!=y` 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>(const id& y) const;
+
+[variablelist
+[[Returns:] [`y<*this`]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[section:less_than_or_equal `operator>=`]
+
+ bool operator<=(const id& y) const;
+
+[variablelist
+[[Returns:] [`!(y<*this)`]]
+[[Throws:] [Nothing]]
+]
+[endsect]
- [section:default_constructor Default Constructor]
+[section:greater_than_or_equal `operator>=`]
- fiber();
+ bool operator>=(const id& y) const;
- [variablelist
- [[Effects:] [Constructs a __fiber__ instance that refers to __not_a_fiber__.]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+[variablelist
+[[Returns:] [`!(*this<y)`]]
+[[Throws:] [Nothing]]
+]
+[endsect]
- [section:callable_constructor Fiber Constructor]
+[section:stream_out Friend `operator<<`]
- template< typename Callable >
- fiber( Callable fn);
+ template<class charT, class traits>
+ friend std::basic_ostream<charT, traits>&
+ operator<<(std::basic_ostream<charT, traits>& os, const id& 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]
- template< typename Callable >
- fiber( std::size_t stack_size, Callable fn);
+[endsect]
- [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:this_fiber Namespace `this_fiber`]
- [section:multiple_argument_constructor Fiber Constructor with arguments]
+[section:get_id Non-member function `get_id()`]
- template< typename Fn, typename A1, typename A2,...>
- fiber( Fn fn,A1 a1,A2 a2,...);
+ #include <boost/fiber/utility.hpp>
- template< typename Fn, typename A1, typename A2,...>
- fiber( std::size_t stack_size, Fn fn,A1 a1,A2 a2,...);
+ namespace this_fiber
+ {
+ fiber::id get_id();
+ }
- [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
+[[Returns:] [An instance of __fiber_id__ that represents that currently executing fiber.]]
+[[Throws:] [__fiber_resource_error__ if an error occurs.]]
+]
+[endsect]
- [section:destructor Fiber Destructor]
+[section:interruption_point Non-member function `interruption_point()`]
- ~fiber();
+ #include <boost/fiber/utility.hpp>
- [variablelist
- [[Effects:] [Destroys `*this`.]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+ 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`.]]
+]
+[endsect]
- [section:get_id Member function `get_id()`]
+[section:interruption_requested Non-member function `interruption_requested()`]
- fiber::id get_id() const;
+ #include <boost/fiber/utility.hpp>
- [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]
+ namespace this_fiber
+ {
+ bool interruption_requested();
+ }
+
+[variablelist
+[[Returns:] [`true` if interruption has been requested for the current fiber, `false` otherwise.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
- [section:join Member function `join()`]
+[section:interruption_enabled Non-member function `interruption_enabled()`]
- void join();
+ #include <boost/fiber/utility.hpp>
- [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]
+ namespace this_fiber
+ {
+ bool interruption_enabled();
+ }
+
+[variablelist
+[[Returns:] [`true` if interruption has been enabled for the current fiber, `false` otherwise.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
- [section:interrupt Member function `interrupt()`]
+[section:cancel Non-member function `cancel()`]
- void interrupt();
+ #include <boost/fiber/utility.hpp>
- [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]
+ namespace this_fiber
+ {
+ void cancel();
+ }
+
+[variablelist
+[[Effects:] [Cancels the current fiber.]]
+[[Throws:] [__fiber_interrupted__ if the current fiber of execution is interrupted.]]
+]
+[endsect]
- [section:interruption_requested Member function `interruption_requested()`]
+[section:yield Non-member function `yield()`]
- bool interruption_requested();
+ #include <boost/fiber/utility.hpp>
- [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]
+ namespace this_fiber
+ {
+ void yield();
+ }
+
+[variablelist
+[[Effects:] [Gives up the remainder of the current fiber's time slice, to allow other fibers to run.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
- [section:cancel Member function `cancel()`]
+[section:disable_interruption Class `disable_interruption`]
- void cancel();
+ #include <boost/fiber/interruption.hpp>
- [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]
+ 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:] [Nothing.]]
+]
+[endsect]
- [section:is_alive Member function `is_alive()`]
+[section:destructor Destructor]
- bool is_alive();
+ ~disable_interruption();
- [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
+[[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]
- [section:unspec_operator `operator unspecified-bool-type() const`]
+[endsect]
- operator unspecified-bool-type() const;
+[section:restore_interruption Class `restore_interruption`]
- [variablelist
- [[Returns:] [If `*this` refers to a fiber, the function returns true. Otherwise false.]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+ #include <boost/fiber/interruption.hpp>
- [section:not_operator `operator!`]
+ 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:] [Nothing.]]
+]
+[endsect]
- bool operator!() const;
+[section:destructor Destructor]
- [variablelist
- [[Returns:] [If `*this` refers not to a fiber, the function returns true. Otherwise false.]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+ ~restore_interruption();
- [section:equals `operator==`]
+[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]
- bool operator==(const fiber& other) const;
+[endsect]
- [variablelist
- [[Returns:] [`get_id()==other.get_id()`]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+[section:atfiberexit Non-member function template `at_fiber_exit()`]
- [section:not_equals `operator!=`]
+ #include <boost/fiber/utility.hpp>
- bool operator!=(const fiber& other) const;
+ template<typename Callable>
+ void at_fiber_exit(Callable func);
- [variablelist
- [[Returns:] [`get_id()!=other.get_id()`]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+[variablelist
+[[Effects:] [A copy of `func` is placed in
+fiber-specific storage. This copy is invoked when the current fiber
+exits (even if the fiber has been interrupted).]]
+[[Postconditions:] [A copy of `func` has been saved for invocation on fiber exit.]]
+[[Throws:] [`std::bad_alloc` if memory cannot be allocated for the copy of the function, __fiber_resource_error__ if any other
+error occurs within the fiber library. Any exception thrown whilst copying `func` into internal storage.]]
+[[Note:] [This function is *not* called if the fiber was terminated
+forcefully using platform-specific APIs, or if the fiber is
+terminated due to a call to `exit()`, `abort()` or
+`std::terminate()`. In particular, returning from `main()` is
+equivalent to call to `exit()`, so will not call any functions
+registered with `at_fiber_exit()`]]
+]
+[endsect]
- [section:swap Member function `swap()`]
+[endsect]
- void swap(fiber& other);
+[section:scheduler_ref Scheduler]
- [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]
+[heading Synopsis]
- [section:non_member_swap Non-member function `swap()`]
+The class `scheduler` is responsible for managing and scheduling of fibers passed to it. The fibers are
+thread-affine, e.g. the fibers remain local for the thread passing the fiber to the scheduler.
+(Maybe futher version of __boost_fiber__ will support explicit migration of fibers between threads.)
- #include <boost/fiber/fiber.hpp>
+Usally `scheduler` will be invoked until all fibers have finished.
- void swap( fiber & lhs, fiber & rhs);
+ boost::fibers::scheduler sched;
+
+ sched.make_fiber( some_fn);
- [variablelist
- [[Effects:] [[link fiber.fiber_management.fiber.swap `lhs.swap( rhs)`].]]
- [[Throws:] [Nothing.]]
- ]
- [endsect]
+ for (;;)
+ {
+ while ( sched.run() );
+ if ( sched.empty() ) break;
+ }
- [section:non_member_make_fiber Non-member template function `make_fiber()`]
- #include <boost/fiber/fiber.hpp>
+[section:scheduler Class `scheduler`]
- template< typename Fn >
- fiber make_fiber( Fn fn);
+ #include <boost/fiber/scheduler.hpp>
- template< typename Fn >
- fiber make_fiber( std::size_t stack_size, Fn fn);
+ class scheduler
+ {
+ public:
+ bool run();
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( Fn fn, A1 a1, A2 a2,...);
+ bool empty();
- template< typename Fn, typename A1, typename A2,... >
- fiber make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ std::size_t size();
- [variablelist
- [[Effects:] [Creates a fiber.]]
- ]
- [endsect]
+ void submit_fiber( fiber);
- [endsect]
+ template< typename Fn >
+ void make_fiber( Fn fn);
+
+ template< typename Fn >
+ void make_fiber( std::size_t stack_size, Fn fn);
+
+ template< typename Fn, typename A1, typename A2,... >
+ void make_fiber( Fn fn, A0 a0, A1 a1,...);
+
+ template< typename Fn, typename A1, typename A2,... >
+ void make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+ };
+
+
+[section:run `run()`]
+
+ bool run();
+
+[variablelist
+[[Effects:] [Executes a fiber from the internal storage and removes terminated fibers. The fnction returns
+`true` if a fiber could be executed or a terminated fiber could be removed - otherwise `false`.]]
+[[Throws:] [__system_error__ if a system call failed.]]
+]
+[endsect]
+
+[section:empty `empty()`]
+
+ bool empty();
+
+[variablelist
+[[Effects:] [Returns `true` if the scheduler contains fibers (maybe runnable or waiting).]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:size `size()`]
+
+ std::size_t size();
+
+[variablelist
+[[Effects:] [Returns how many fibers the scheduler contains (maybe runnable or waiting).]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:submit_fiber `submit_fiber( fiber f)`]
+
+ void submit_fiber( fiber f);
+
+[variablelist
+[[Effects:] [This function stores the passed fiber in the scheduler.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[section:make_fiber `make_fiber()`]
+
+ template< typename Fn >
+ void make_fiber( Fn fn);
+
+ template< typename Fn >
+ void make_fiber( std::size_t stack_size, Fn fn);
+
+ template< typename Fn, typename A1, typename A2,... >
+ void make_fiber( Fn fn, A0 a0, A1 a1,...);
+
+ template< typename Fn, typename A1, typename A2,... >
+ void make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+
+[variablelist
+[[Effects:] [The functionscreate a fiber which gets stored in the internal structures from scheduler.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+[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-21 16:43:40 EST (Sat, 21 Nov 2009)
@@ -7,278 +7,277 @@
[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]
-
- [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]
+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]
+
+[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]
- [endsect]
+[section:constructor_adopt `unique_lock(Lockable & m,boost::adopt_lock_t)`]
- [endsect]
+[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]
+
+[endsect]
[endsect]
Deleted: sandbox/fiber/libs/fiber/doc/scheduler.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/scheduler.qbk 2009-11-21 16:43:40 EST (Sat, 21 Nov 2009)
+++ (empty file)
@@ -1,123 +0,0 @@
-[/
- Copyright Oliver Kowalke 2009.
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt
-
- Based on documentation from Boost.Thread.
-]
-
-[section:scheduler_ref Scheduler]
-
-[heading Synopsis]
-
-The class `scheduler` is responsible for managing and scheduling of fibers passed to it. The fibers are
-thread-affine, e.g. the fibers remain local for the thread passing the fiber to the scheduler.
-(Maybe futher version of __boost_fiber__ will support explicit migration of fibers between threads.)
-
-Usally `scheduler` will be invoked until all fibers have finished.
-
- boost::fibers::scheduler sched;
-
- sched.make_fiber( some_fn);
-
- for (;;)
- {
- while ( sched.run() );
- if ( sched.empty() ) break;
- }
-
-
-[section:scheduler Class `scheduler`]
-
- #include <boost/fiber/scheduler.hpp>
-
- class scheduler
- {
- public:
- bool run();
-
- bool empty();
-
- std::size_t size();
-
- void submit_fiber( fiber);
-
- template< typename Fn >
- void make_fiber( Fn fn);
-
- template< typename Fn >
- void make_fiber( std::size_t stack_size, Fn fn);
-
- template< typename Fn, typename A1, typename A2,... >
- void make_fiber( Fn fn, A0 a0, A1 a1,...);
-
- template< typename Fn, typename A1, typename A2,... >
- void make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
- };
-
-
-[section:run `run()`]
-
- bool run();
-
-[variablelist
-[[Effects:] [Executes a fiber from the internal storage and removes terminated fibers. The fnction returns
-`true` if a fiber could be executed or a terminated fiber could be removed - otherwise `false`.]]
-[[Throws:] [__system_error__ if a system call failed.]]
-]
-[endsect]
-
-[section:empty `empty()`]
-
- bool empty();
-
-[variablelist
-[[Effects:] [Returns `true` if the scheduler contains fibers (maybe runnable or waiting).]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:size `size()`]
-
- std::size_t size();
-
-[variablelist
-[[Effects:] [Returns how many fibers the scheduler contains (maybe runnable or waiting).]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:submit_fiber `submit_fiber( fiber f)`]
-
- void submit_fiber( fiber f);
-
-[variablelist
-[[Effects:] [This function stores the passed fiber in the scheduler.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[section:make_fiber `make_fiber()`]
-
- template< typename Fn >
- void make_fiber( Fn fn);
-
- template< typename Fn >
- void make_fiber( std::size_t stack_size, Fn fn);
-
- template< typename Fn, typename A1, typename A2,... >
- void make_fiber( Fn fn, A0 a0, A1 a1,...);
-
- template< typename Fn, typename A1, typename A2,... >
- void make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
-
-[variablelist
-[[Effects:] [The functionscreate a fiber which gets stored in the internal structures from scheduler.]]
-[[Throws:] [Nothing.]]
-]
-[endsect]
-
-[endsect]
-
-[endsect]
Modified: sandbox/fiber/libs/fiber/doc/todo.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/todo.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/todo.qbk 2009-11-21 16:43:40 EST (Sat, 21 Nov 2009)
@@ -15,7 +15,7 @@
* replace system calls related to fiber switching (like swapcontext()) by assembler
-* explicit migraton of fiber between schedulers (that measn threads)
+* explicit migraton of fiber between schedulers (== between threads)
* improve scheduling algorithm (take priorities into acount)
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