Merge branch 'fiber-mt' of git://github.com/nat-goodspeed/boost-fiber into nat-goodspeed-fiber-mt

Conflicts:
	doc/scheduling.qbk

doc/overview.qbk

@@ -21,8 +21,8 @@ The idea is to have multiple execution paths running on a single thread using a
 sort of cooperative scheduling (versus threads, which are preemptively scheduled). The
 running fiber decides explicitly when it should yield to allow another fiber to
 run (context switching).
-__boost_fiber__ uses internaly coroutines from __boost_coroutine__ and the classes in
-this library enable to synchronize those corutines.
+__boost_fiber__ internally uses coroutines from __boost_coroutine__; the classes in
+this library manage, schedule and, when needed, synchronize those coroutines.
 A context switch between threads usually costs thousands of CPU cycles on x86,
 compared to a fiber switch with a few hundred cycles.
 A fiber can only run on a single thread at any point in time.

doc/queue.qbk

@@ -166,13 +166,13 @@ fiber gets suspended until at least one new item is `push()`ed (return value
                                       chrono::duration< Rep, Period > const& timeout_duration)
 
 [variablelist
-[[Effects:] [Accepts `chrono::duration` internally
+[[Effects:] [Accepts `chrono::duration` and internally
 computes a `clock_type::time_point` as `(clock_type::now() +
 timeout_duration)`. If `(! this->is_empty())`, immediately dequeues a value
 from the queue. Otherwise the fiber gets suspended until at least one new item
 is `push()`ed (return value `success` and `va` contains dequeued value), or
 the queue gets `close()`d (return value `closed`), or the time as reported by
-`clock_type::now()` reaches the (passed or computed) `clock_type::time_point`
+`clock_type::now()` reaches the computed `clock_type::time_point`
 (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted__]]
 ]
@@ -187,7 +187,7 @@ the queue gets `close()`d (return value `closed`), or the time as reported by
 immediately dequeues a value from the queue. Otherwise the fiber gets suspended
 until at least one new item is `push()`ed (return value `success` and `va`
 contains dequeued value), or the queue gets `close()`d (return value `closed`),
-or the time as reported by `clock_type::now()` reaches the (passed or computed)
+or the time as reported by `clock_type::now()` reaches the passed
 `clock_type::time_point` (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted__]]
 ]
@@ -343,7 +343,7 @@ queue drops below `lwm` (return value `success`), or the queue is `close()`d
                                        chrono::duration< Rep, Period > const& timeout_duration);
 
 [variablelist
-[[Effects:] [Accepts `chrono::duration` internally
+[[Effects:] [Accepts `chrono::duration` and internally
 computes a `clock_type::time_point` as `(clock_type::now() +
 timeout_duration)`. If `this->is_closed()`, returns `closed`. If `(!
 this->is_full())`, enqueues the value in the queue, wakes up a fiber blocked
@@ -351,7 +351,7 @@ on `this->pop()` `this->pop_wait_for()` or `this->pop_wait_until()` and returns
 `success`. Otherwise the fiber gets suspended until the number of values in the
 queue drops below `lwm` (return value `success`), the queue is `close()`d
 (return value `closed`), or the time as reported by `clock_type::now()` reaches
-the (passed or computed) `clock_type::time_point` (return value `timeout`).]]
+the computed `clock_type::time_point` (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted_]]
 ]
 
@@ -369,7 +369,7 @@ fiber blocked on `this->pop()`, `this->pop_wait_for()` or `this->pop_wait_until(
 and returns `success`. Otherwise the fiber gets suspended until the number of
 values in the queue drops below `lwm` (return value `success`), the queue is
 `close()`d (return value `closed`), or the time as reported by `clock_type::now()`
-reaches the (passed or computed) `clock_type::time_point` (return value `timeout`).]]
+reaches the passed `clock_type::time_point` (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted_]]
 ]
 
@@ -407,13 +407,13 @@ drops below `lwm`, any fibers blocked on `push()`, `push_wait_for()` or
                                       chrono::duration< Rep, Period > const& timeout_duration)
 
 [variablelist
-[[Effects:] [First the overload accepting `chrono::duration` internally
+[[Effects:] [Accepts `chrono::duration` and internally
 computes a `clock_type::time_point` as `(clock_type::now() +
 timeout_duration)`. If `(! this->is_empty())`, immediately dequeues a value
 from the queue. Otherwise the fiber gets suspended until at least one new item
 is `push()`ed (return value `success` and `va` contains dequeued value), or
 the queue gets `close()`d (return value `closed`), or the time as reported by
-`clock_type::now()` reaches the (passed or computed) `clock_type::time_point`
+`clock_type::now()` reaches the computed `clock_type::time_point`
 (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted__]]
 ]
@@ -428,7 +428,7 @@ the queue gets `close()`d (return value `closed`), or the time as reported by
 immediately dequeues a value from the queue. Otherwise the fiber gets suspended
 until at least one new item is `push()`ed (return value `success` and `va`
 contains dequeued value), or the queue gets `close()`d (return value `closed`),
-or the time as reported by `clock_type::now()` reaches the (passed or computed)
+or the time as reported by `clock_type::now()` reaches the passed
 `clock_type::time_point` (return value `timeout`).]]
 [[Throws:] [__fiber_interrupted__]]
 ]

doc/scheduling.qbk

@@ -63,8 +63,8 @@ schedulers - `round_robin` and `round_robin_ws`.
         virtual void spawn( detail::fiber_base::ptr_t const& f) = 0;
 
 [variablelist
-[[Returns:] [Spawns fiber `f`, e.g. `f` will be entered the first time or
-or resumed where it was suspended before.]]
+[[Effects:] [Spawns fiber `f`, e.g. `f` will be entered the first time
+or resumed where it was suspended before. Suspends the current fiber.]]
 ]
 
 [member_heading algorithm..priority]
@@ -72,7 +72,8 @@ or resumed where it was suspended before.]]
         virtual void priority( detail::fiber_base::ptr_t const& f, int p) noexcept = 0;
 
 [variablelist
-[[Returns:] [Sets the priority `p` for fiber `f`]]
+[[Effects:] [Sets priority `p` for fiber `f`. Interpretation of "priority"
+is entirely up to the subclass.]]
 [[Throws:] [Nothing]]
 ]
 
@@ -81,7 +82,7 @@ or resumed where it was suspended before.]]
         virtual void join( detail::fiber_base::ptr_t const& f) = 0;
 
 [variablelist
-[[Returns:] [The current execution context gets suspended until fiber `f` terminates.]]
+[[Effects:] [Suspends the current fiber until fiber `f` terminates.]]
 ]
 
 [member_heading algorithm..active]
@@ -89,7 +90,8 @@ or resumed where it was suspended before.]]
         virtual detail::fiber_base::ptr_t active() noexcept = 0;
 
 [variablelist
-[[Returns:] [Returns the active fiber or a null-pointer otherwise.]]
+[[Returns:] [Returns the active fiber, or a null-pointer if the current
+execution context is not a fiber managed by this __algo__ instance.]]
 ]
 
 [member_heading algorithm..run]
@@ -97,6 +99,8 @@ or resumed where it was suspended before.]]
         virtual bool run() = 0;
 
 [variablelist
+[[Effects:] [Selects one fiber in ready state and runs it until it suspends.
+The choice of fiber is up to the subclass instance.]]
 [[Returns:] [Returns `true` if one fiber was ready and successfully executed, `false`
 otherwise.]]
 ]
@@ -106,7 +110,7 @@ otherwise.]]
         virtual void wait( unique_lock< detail::spinlock > & lk) = 0;
 
 [variablelist
-[[Precondition:] [`lk` is locked by the current fiberi. It locks the spinlock
+[[Precondition:] [`lk` is locked by the current fiber. It locks the spinlock
 protecting the internal state of a mutex or condition_variable.]]
 [[Effects:] [Current fiber is set to waiting-state and gets suspended.]]
 [[Postcondition:] [`lk` is unlocked.]]
@@ -118,11 +122,11 @@ protecting the internal state of a mutex or condition_variable.]]
                                  unique_lock< detail::spinlock > & lk) = 0;
 
 [variablelist
-[[Precondition:] [`lk` is locked by the current fiberi. It locks the spinlock
+[[Precondition:] [`lk` is locked by the current fiber. It locks the spinlock
 protecting the internal state of a mutex or condition_variable.]]
 [[Effects:] [Current fiber is set to waiting-state and gets suspended.]]
 [[Returns:] [Returns `true` if fiber was resumed before time-point
-`timeout_time` was elapsed, `false` otherwise.]]
+`timeout_time` was reached, `false` otherwise.]]
 [[Postcondition:] [`lk` is unlocked.]]
 ]
 
@@ -133,7 +137,7 @@ protecting the internal state of a mutex or condition_variable.]]
                        unique_lock< detail::spinlock > & lk)
 
 [variablelist
-[[Precondition:] [`lk` is locked by the current fiberi. It locks the spinlock
+[[Precondition:] [`lk` is locked by the current fiber. It locks the spinlock
 protecting the internal state of a mutex or condition_variable.]]
 [[Effects:] [Current fiber is set to waiting-state and gets suspended.]]
 [[Returns:] [Returns `true` if fiber was resumed before time-duration
@@ -146,7 +150,8 @@ protecting the internal state of a mutex or condition_variable.]]
         virtual void yield() = 0;
 
 [variablelist
-[[Effects:] [Suspends active fiber while immediately set to ready-state.]]
+[[Effects:] [Suspends active fiber without waiting; that is, the current fiber
+is immediately set to ready-state.]]
 ]
 
 [member_heading algorithm..get_main_id]
@@ -154,8 +159,8 @@ protecting the internal state of a mutex or condition_variable.]]
         virtual detail::fiber_base::id get_main_id() = 0;
 
 [variablelist
-[[Returns:] [Returns a `fiber_base::id` associated to the thread the scheduler
-is running while no fiber is active.]]
+[[Returns:] [Returns a `fiber_base::id` associated to the thread on which the
+scheduler is running while no fiber is active.]]
 ]
 
 
@@ -168,7 +173,7 @@ This class implements __algo__ and schedules fibers in round-robin fashion.
 `round_robin_ws` is intended to be used for migrating fibers between threads (different
 schedulers). For this purpose the class has two additional functions - `steal_from()` and
 `migrate_to()`.
-This functionality can be used to implement work-stealing/-sharing in a threadpool .
+This functionality can be used to implement work-stealing/-sharing in a threadpool.
 
         // steal a fiber from a scheduler `other_ds` running in another thread
         boost::fibers::fiber f( other_ds->steal_from() );