diff --git a/doc/overview.qbk b/doc/overview.qbk index 12dff43e..37a27c6a 100644 --- a/doc/overview.qbk +++ b/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. diff --git a/doc/queue.qbk b/doc/queue.qbk index 39da06dd..51eee8b8 100644 --- a/doc/queue.qbk +++ b/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__]] ] diff --git a/doc/scheduling.qbk b/doc/scheduling.qbk index 01450153..38a51afb 100644 --- a/doc/scheduling.qbk +++ b/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() );