|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r58341 - in sandbox/fiber: . libs/fiber/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-12-13 05:40:26
Author: olli
Date: 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
New Revision: 58341
URL: http://svn.boost.org/trac/boost/changeset/58341
Log:
- docu modified
Added:
sandbox/fiber/libs/fiber/doc/barrier.qbk (contents, props changed)
Text files modified:
sandbox/fiber/change.log | 11 +
sandbox/fiber/libs/fiber/doc/condition_variables.qbk | 114 +++++++++++------
sandbox/fiber/libs/fiber/doc/event_variables.qbk | 3
sandbox/fiber/libs/fiber/doc/fiber.qbk | 68 ++++++----
sandbox/fiber/libs/fiber/doc/fiber_ref.qbk | 242 ++++++++++++++++++++++++++++++++-------
sandbox/fiber/libs/fiber/doc/fifos.qbk | 8
sandbox/fiber/libs/fiber/doc/mutexes.qbk | 3
sandbox/fiber/libs/fiber/doc/overview.qbk | 2
sandbox/fiber/libs/fiber/doc/todo.qbk | 6
9 files changed, 332 insertions(+), 125 deletions(-)
Modified: sandbox/fiber/change.log
==============================================================================
--- sandbox/fiber/change.log (original)
+++ sandbox/fiber/change.log 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -1,10 +1,17 @@
+0.3.1:
+------
+- scheduler< Strategy >::migrate_fiber() overloaded - passing only fiber to be migrated
+
0.3.0:
------
+- support of barrier (more efficient in on scheduler) and spin::barrier
+ (sync .between threads possible)
+- support of future and packaged_task (example future_mt)
- explicit migration of fibers between two schedulers
(even if schedulers are in different threads - see example migrate_mt)
- locks replaced by locks implementation from boost.thread
-- introduction of spin_mutex, spin_condition, spin_auto_reset_event, ...
- (can be used to sync fibers between threads)
+- introduction of spin::mutex, spin::condition, spin::auto_reset_event, ...
+ (can be used to sync fibers between threads see ping_pong_mt example)
- introduction of mutex, condition, auto_reset_event, ...
(objects bounded to one scheduler, but more efficient than spin counter-parts)
- refactoring of internal classes
Added: sandbox/fiber/libs/fiber/doc/barrier.qbk
==============================================================================
--- (empty file)
+++ sandbox/fiber/libs/fiber/doc/barrier.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -0,0 +1,57 @@
+[/
+ (C) Copyright 2007-8 Anthony Williams.
+ 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).
+]
+
+[section:barriers Barriers]
+
+A barrier is a simple concept. Also known as a __rendezvous__, it is a synchronization point between multiple
+contexts of execution (thread or fiber). The barrier is configured for a particular number of fibers (`n`), and as
+fibers reach the barrier they must wait until all `n` fibers have arrived. Once the `n`-th fiber has reached the
+barrier, all the waiting fibers can proceed, and the barrier is reset.
+
+[note __barrier__ is bound to a given __scheduler__ and can only be used by fibers managed by this scheduler.]
+
+[section:barrier Class `barrier`]
+
+ #include <boost/fiber/barrier.hpp>
+
+ class barrier
+ {
+ public:
+ template< typename Strategy >
+ barrier( scheduler< Strategy > & sched, uint32_t initial);
+
+ bool wait();
+ };
+
+Instances of __barrier__ are not copyable or movable.
+
+[section:constructor Constructor]
+
+ template< typename Strategy >
+ barrier( scheduler< Strategy > & sched, uint32_t initial);
+
+[variablelist
+[[Effects:] [Construct a barrier for `initial` fibers.]]
+[[Throws:] [__invalid_argument__ if an error occurs.]]
+]
+[endsect]
+
+[section:wait Member function `wait`]
+
+ bool wait();
+
+[variablelist
+[[Effects:] [Block until `initial` fibers have called `wait` on `*this`. When the `initial`-th fiber calls `wait`,
+all waiting fibers are unblocked, and the barrier is reset. ]]
+[[Returns:] [`true` for exactly one fiber from each batch of waiting fibers, `false` otherwise.]]
+[[Throws:] [__fiber_error__ if an error occurs.]]
+]
+[endsect]
+
+[endsect]
+
+[endsect]
Modified: sandbox/fiber/libs/fiber/doc/condition_variables.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/condition_variables.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/condition_variables.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -5,26 +5,25 @@
http://www.boost.org/LICENSE_1_0.txt).
]
-[section:condvar_ref Condition Variables]
+[section:conditions Condition Variables]
[heading Synopsis]
-The class `condition` provides a mechanism for one fiber to wait for notification
-`condition` or `condition_any`. When the fiber is woken from
-the wait, then it checks to see if the appropriate condition is now true, and
-continues if so. If the condition is not true, then the fiber then calls `wait`
-again to resume waiting. In the simplest case, this condition is just a boolean
-variable:
-
- boost::fibers::condition cond;
- boost::fibers::mutex mtx;
+The class `condition` provides a mechanism for one fiber to wait for notification `condition`. When the fiber is
+woken from the wait, then it checks to see if the appropriate condition is now true, and continues if so. If the
+condition is not true, then the fiber then calls `wait` again to resume waiting. In the simplest case, this
+condition is just a boolean variable:
+
+ boost::fibers::scheduler<> sched;
+ boost::fibers::condition cond( sched);
+ boost::fibers::mutex mtx( sched);
bool data_ready;
void process_data();
void wait_for_data_to_process()
{
- boost::fibers::unique_lock< boost::fibers::mutex > lk( mtx);
+ boost::unique_lock< boost::fibers::mutex > lk( mtx);
while ( ! data_ready)
{
cond.wait( lk);
@@ -32,16 +31,13 @@
process_data();
}
-Notice that the `lk` is passed to `wait`: `wait` will atomically add the
-fiber to the set of fibers waiting on the condition variable, and unlock the
-mutex. When the fiber is woken, the mutex will be locked again before the call
-to `wait` returns. This allows other fibers to acquire the mutex in order to
-update the shared data, and ensures that the data associated with the condition
-is correctly synchronized.
-
-In the mean time, another fiber sets the condition to `true`, and then calls
-either `notify_one` or `notify_all` on the condition variable to wake one
-waiting fiber or all the waiting fibers respectively.
+Notice that the `lk` is passed to `wait`: `wait` will atomically add the fiber to the set of fibers waiting on the
+condition variable, and unlock the mutex. When the fiber is woken, the mutex will be locked again before the call
+to `wait` returns. This allows other fibers to acquire the mutex in order to update the shared data, and ensures
+that the data associated with the condition is correctly synchronized.
+
+In the mean time, another fiber sets the condition to `true`, and then calls either `notify_one` or `notify_all` on
+the condition variable to wake one waiting fiber or all the waiting fibers respectively.
void retrieve_data();
void prepare_data();
@@ -57,8 +53,10 @@
cond.notify_one();
}
-Note that the same mutex is locked before the shared data is updated, but that
-the mutex does not have to be locked across the call to `notify_one`.
+Note that the same mutex is locked before the shared data is updated, but that the mutex does not have to be locked
+across the call to `notify_one`.
+
+[note __condition__ is bound to a given __scheduler__ an can only be used by fibers managed by this scheduler.]
[section:condition Class `condition`]
@@ -67,16 +65,23 @@
class condition
{
public:
- condition();
+ template< typename Strategy >
+ condition( scheduler< Strategy > & sched);
~condition();
void notify_one();
void notify_all();
- void wait( boost::fibers::unique_lock< boost::fibers::mutex > & lk);
+ void wait( boost::unique_lock< boost::fibers::mutex > & lk);
- template< typename predicate_type >
- void wait( boost::fibers::unique_lock< boost::fibers::mutex > & lk,predicate_type predicate);
+ template< typename Pred >
+ void wait( boost::unique_lock< boost::fibers::mutex > & lk, Pred pred);
+
+ template< typename LockType >
+ void wait( LockType & lk);
+
+ template< typename LockType, typename Pred >
+ void wait( LockType & lk, Pred predicate);
};
[section:constructor `condition()`]
@@ -88,9 +93,8 @@
[section:destructor `~condition()`]
[variablelist
-[[Precondition:] [All fibers waiting on `*this` have been notified by a call to
-`notify_one` or `notify_all` (though the respective calls to `wait` need not have
-returned).]]
+[[Precondition:] [All fibers waiting on `*this` have been notified by a call to `notify_one` or `notify_all`
+(though the respective calls to `wait` need not have returned).]]
[[Effects:] [Destroys the object.]]
[[Throws:] [Nothing.]]
]
@@ -98,42 +102,68 @@
[section:notify_one `void notify_one()`]
[variablelist
-[[Effects:] [If any fibers are currently __blocked__ waiting on `*this` in a call
-to `wait`, unblocks one of those fibers.]]
+[[Effects:] [If any fibers are currently __blocked__ waiting on `*this` in a call to `wait`, unblocks one of
+those fibers.]]
[[Throws:] [Nothing.]]
]
[endsect]
[section:notify_all `void notify_all()`]
[variablelist
-[[Effects:] [If any fibers are currently __blocked__ waiting on `*this` in a call
-to `wait`, unblocks all of those fibers.]]
+[[Effects:] [If any fibers are currently __blocked__ waiting on `*this` in a call to `wait`, unblocks all of
+those fibers.]]
[[Throws:] [Nothing.]]
]
[endsect]
-[section:wait `void wait( boost::fibers::unique_lock< boost::fibers::mutex> & lk)`]
+[section:wait `void wait( boost::unique_lock< boost::fibers::mutex > & lk)`]
[variablelist
-[[Precondition:] [`lock` is locked by the current fiber, and either no other
+[[Precondition:] [`lk` is locked by the current fiber, and either no other
fiber is currently waiting on `*this`, or the execution of the `mutex()` member
function on the `lk` objects supplied in the calls to `wait` in all the fibers
-currently waiting on `*this` would return the same value as `lock->mutex()` for
+currently waiting on `*this` would return the same value as `lk->mutex()` for
this call to `wait`.]]
-[[Effects:] [Atomically call `lock.unlock()` and blocks the current fiber. The
+[[Effects:] [Atomically call `lk.unlock()` and blocks the current fiber. The
fiber will unblock when notified by a call to `this->notify_one()` or
`this->notify_all()`, or spuriously. When the fiber is unblocked (for whatever
-reason), the lock is reacquired by invoking `lock.lock()` before the call to
-`wait` returns. The lock is also reacquired by invoking `lock.lock()` if the
+reason), the lock is reacquired by invoking `lk.lock()` before the call to
+`wait` returns. The lock is also reacquired by invoking `lk.lock()` if the
function exits with an exception.]]
-[[Postcondition:] [`lock` is locked by the current fiber.]]
+[[Postcondition:] [`lk` is locked by the current fiber.]]
[[Throws:] [__fiber_error__ if an error
occurs. __fiber_interrupted__ if the wait was interrupted by a call to
__interrupt__ on the __fiber__ object associated with the current fiber of execution.]]
+]
+[endsect]
+
+[section:wait_predicate `template< typename Pred > void wait( boost::unique_lock< boost::fibers::mutex > & lk, Pred pred)`]
+[variablelist
+[[Effects:] [As-if ``
+while ( ! pred())
+{
+ wait( lk);
+}
+``]]
+
+]
+[endsect]
+[section:wait_t `template< typename LockType > void wait( LockType & lk)`]
+[variablelist
+[[Effects:] [Atomically call `lk.unlock()` and blocks the current fiber. The
+fiber will unblock when notified by a call to `this->notify_one()` or
+`this->notify_all()`, or spuriously. When the fiber is unblocked (for whatever
+reason), the lock is reacquired by invoking `lk.lock()` before the call to
+`wait` returns. The lock is also reacquired by invoking `lk.lock()` if the
+function exits with an exception.]]
+[[Postcondition:] [`lk` is locked by the current fiber.]]
+[[Throws:] [__fiber_error__ if an error
+occurs. __fiber_interrupted__ if the wait was interrupted by a call to
+__interrupt__ on the __fiber__ object associated with the current fiber of execution.]]
]
[endsect]
-[section:wait_predicate `void wait( boost::fibers::unique_lock< boost::fibers::mutex > & lk, predicate_type pred)`]
+[section:wait_predicate_t `template< typename LockType, typename Pred > void wait( LockType & lk, Pred pred)`]
[variablelist
[[Effects:] [As-if ``
while ( ! pred())
Modified: sandbox/fiber/libs/fiber/doc/event_variables.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/event_variables.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/event_variables.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -12,6 +12,9 @@
__boost_fiber__ provides event variables to facilitate coordination between fibers.
A event-variable has two states `set` (`signaled`) or `reset` (`nonsignaled`).
+[note event-variables are bound to a given __scheduler__ an can only be used by fibers
+managed by this scheduler.]
+
boost::fibers::auto_reset_event ev;
void process_data();
Modified: sandbox/fiber/libs/fiber/doc/fiber.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/fiber.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/fiber.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -18,51 +18,62 @@
]
]
+
[def __boost_fiber__ [*Boost.Fiber]]
[def __boost_task__ [*Boost.Task]]
[def __boost_thread__ [*Boost.Thread]]
+[template barrier_link[link_text] [link fiber.synchronization.barriers [link_text]]]
+[template condition_link[link_text] [link fiber.synchronization.conditions [link_text]]]
+[template fiber_link[link_text] [link fiber.fiber_management.fiber [link_text]]]
+[template fiber_id_link[link_text] [link fiber.fiber_management.fiber.id [link_text]]]
+[template mutex_link[link_text] [link fiber.synchronization.mutex_types.mutex [link_text]]]
+[template scheduler_link[link_text] [link fiber.fiber_management.scheduler [link_text]]]
+[template strategy_link[link_text] [link fiber.fiber_management.strategy [link_text]]]
+[template round_robin_link[link_text] [link fiber.fiber_management.round_robin [link_text]]]
+
+[template auto_reset_wait_link[link_text] [link fiber.synchronization.eventvar_ref.auto_reset_event.wait [link_text]]]
+[template cond_wait_link[link_text] [link fiber.synchronization.conditions.condition.wait [link_text]]]
+[template interrupt_link[link_text] [link fiber.fiber_management.fiber.interrupt [link_text]]]
+[template join_link[link_text] [link fiber.fiber_management.fiber.join [link_text]]]
+
+[template interr_enabled_link[link_text] [link fiber.fiber_management.this_fiber.interruption_enabled [link_text]]]
+[template interr_requested_link[link_text] [link fiber.fiber_management.this_fiber.interruption_requested [link_text]]]
+[template interr_point_link[link_text] [link fiber.fiber_management.this_fiber.interruption_point [link_text]]]
+[template disable_interr_link[link_text] [link fiber.fiber_management.this_fiber.disable_interruption [link_text]]]
+[template restore_interr_link[link_text] [link fiber.fiber_management.this_fiber.restore_interruption [link_text]]]
+
[def __blocked__ ['blocked]]
-[def __fiber__ ['fiber]]
-[def __interruption_points__ [link interruption_points ['interruption points]]]
[def __not_a_fiber__ ['not-a-fiber]]
-[def __scheduler__ ['scheduler]]
-[def __strategy__ ['strategy]]
[def __lockable_concept__ ['lockable concept]]
+[def __rendezvous__ ['rendezvous]]
-[template mutex_func_ref_link[link_text] [link fiber.synchronization.locks.unique_lock.mutex [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.wait [link_text]]]
-[template cond_any_wait_link[link_text] [link fiber.synchronization.condvar_ref.condition_variable_any.wait [link_text]]]
-[template auto_reset_wait_link[link_text] [link fiber.synchronization.eventvar_ref.auto_reset_event.wait [link_text]]]
-[template manual_reset_wait_link[link_text] [link fiber.synchronization.eventvar_ref.manual_reset_event.wait [link_text]]]
-[template count_down_wait_link[link_text] [link fiber.synchronization.eventvar_ref.count_down_event.wait [link_text]]]
-
-[def __mutex_func_ref__ [mutex_func_ref_link `mutex()`]]
-[def __mutex__ [link fiber.synchronization.mutex_types.mutex `boost::fibers::mutex`]]
-[def __lock_ref__ `lock()`]
-[def __try_lock_ref__ `try_lock()`]
-[def __unlock_ref__ `unlock()`]
+[def __barrier__ [barrier_link ['barrier]]]
+[def __condition__ [condition_link ['condition]]]
+[def __fiber__ [fiber_link ['fiber]]]
+[def __fiber_id__ [fiber_id_link ['fiber-id]]]
+[def __mutex__ [mutex_link ['mutex]]]
+[def __scheduler__ scheduler_link['scheduler]]
+[def __strategy__ strategy_link['strategy]]
+[def __round_robin__ round_robin_link['round_robin]]
-[def __fiber__ [link fiber.fiber_management.fiber `boost::fiber`]]
-[def __fiber_id__ [link fiber.fiber_management.fiber.id `boost::fiber::id`]]
+[def __cond_wait__ [cond_wait_link `wait()`]]
+[def __interrupt__ [interrupt_link `interrupt()`]]
[def __join__ [join_link `join()`]]
-[def __interrupt__ [link fiber.fiber_management.fiber.interrupt `interrupt()`]]
-[def __interruption_enabled__ [link fiber.fiber_management.this_fiber.interruption_enabled `boost::this_fiber::interruption_enabled()`]]
-[def __interruption_requested__ [link fiber.fiber_management.this_fiber.interruption_requested `boost::this_fiber::interruption_requested()`]]
-[def __interruption_point__ [link fiber.fiber_management.this_fiber.interruption_point `boost::this_fiber::interruption_point()`]]
-[def __disable_interruption__ [link fiber.fiber_management.this_fiber.disable_interruption `boost::this_fiber::disable_interruption`]]
-[def __restore_interruption__ [link fiber.fiber_management.this_fiber.restore_interruption `boost::this_fiber::restore_interruption`]]
+[def __interruption_enabled__ [interr_enabled_link `boost::this_fiber::interruption_enabled()`]]
+[def __interruption_requested__ [interr_requested_link `boost::this_fiber::interruption_requested()`]]
+[def __interruption_point__ [interr_point_link `boost::this_fiber::interruption_point()`]]
+[def __disable_interruption__ [disable_interr_link `boost::this_fiber::disable_interruption`]]
+[def __restore_interruption__ [restore_interr_link `boost::this_fiber::restore_interruption`]]
-[def __fiber_interrupted__ `boost::fibers::fiber_interrupted`]
[def __fiber_error__ `boost::fibers::fiber_error`]
+[def __fiber_interrupted__ `boost::fibers::fiber_interrupted`]
[def __fiber_moved__ `boost::fibers::fiber_moved`]
+[def __invalid_argument__ `std::invalid_argument`]
[def __lock_error__ `boost::fibers::lock_error`]
[def __system_error__ `boost::system::system_error`]
-[def __cond_wait__ [cond_wait_link `wait()`]]
-[def __cond_any_wait__ [cond_any_wait_link `wait()`]]
[include overview.qbk]
@@ -70,6 +81,7 @@
[section:synchronization Synchronization]
[include mutexes.qbk]
[include condition_variables.qbk]
+[include barrier.qbk]
[include event_variables.qbk]
[include fifos.qbk]
[endsect]
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-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -777,18 +777,18 @@
[endsect]
-[section:scheduler_ref Scheduler]
+[section:scheduler Scheduler]
[heading Synopsis]
-The template __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.)
+The template __scheduler__ is responsible for managing and scheduling of fibers passed to it. The scheduling-
+algorithm is provided as an template argument to __scheduler__ (default is __round_robin__). The class implementing
+the scheduling algorithm must derive from class __strategy__. It is possible to migrate fibers between schedulers.
-The scheduling-algorithm is provided as an template arguemnt to __scheduler__. The class implementing the
-scheduling algorithm must derive from class __strategy__.
+[note If the fiber is not thread-affine (using thread-local-storage) it can be migrated to a scheduler running in
+another thread.]
-Usally __scheduler__ will be invoked until all fibers have finished.
+Usally __scheduler__ will be invoked until all fibers are scheduled and finished.
boost::fibers::scheduler<> sched;
@@ -801,7 +801,7 @@
}
-[section:scheduler Template `scheduler`]
+[section:scheduler Template `template< typename Strategy > scheduler`]
#include <boost/fiber/scheduler.hpp>
@@ -832,6 +832,11 @@
template< typename Fn, typename A1, typename A2,... >
void make_fiber( std::size_t stack_size, Fn fn, A1 a1, A2 a2,...);
+
+ void migrate_fiber( fiber f);
+
+ template< typename OtherStrategy >
+ void migrate_fiber( fiber::id const& id, scheduler< OtherStrategy & sched);
};
@@ -851,7 +856,7 @@
~scheduler();
[variablelist
-[[Effects:] [Destroys the scheduler.]]
+[[Effects:] [Detaches all managed fibers and destroys the scheduler.]]
[[Throws:] [Nothing.]]
]
[endsect]
@@ -862,7 +867,7 @@
bool run();
[variablelist
-[[Effects:] [Executes a fiber from the internal storage and removes terminated fibers. The fnction returns
+[[Effects:] [Executes a fiber from the internal storage and removes terminated fibers. The function 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.]]
]
@@ -913,23 +918,44 @@
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.]]
+[[Effects:] [The functions create a fiber which gets stored in the internal structures from scheduler.]]
[[Throws:] [Nothing.]]
]
[endsect]
+[section:migrate_fiber member function `migrate_fiber( fiber f)`]
+
+ void migrate_fiber( fiber f);
+
+[variablelist
+[[Effects:] [The fiber will be migrated to the scheduler.]]
+[[Throws:] [Throws __fiber_moved_, fiber_error, scheduler_error.]]
+]
+[endsect]
+
+[section:migrate_fiber_t Template member function `template< typename OtherStrategy > migrate_fiber( fiber::id const& id, scheduler< OtherStrategy > & sched)`]
+
+ template< typename OtherStrategy >
+ void migrate_fiber( fiber::id const& id, scheduler< OtherStrategy > & sched);
+
+[variablelist
+[[Effects:] [The fiber will be migrated to the scheduler.]]
+[[Throws:] [Throws __fiber_moved_, fiber_error, scheduler_error.]]
+]
[endsect]
[endsect]
-[section:strategy_ref Strategy]
+[endsect]
+
+[section:strategy Strategy]
[heading Synopsis]
The template __scheduler__ accepts the implementation of the scheduling-algorithm as a template argument
(currently round-robin is the choosen as the default).
-Each class destined to implement a scheduling algorithm must derive from __strategy__. The memeber `active_fiber`
-old the current (running) fiber and `master_fiber` executes the scheduling logic.
+Each class destined to implement a scheduling algorithm must derive from __strategy__. The member `active_fiber`
+holds the current (running) fiber and `master_fiber` executes the scheduling logic.
[section:strategy Class `strategy`]
@@ -957,12 +983,14 @@
bool in_state_not_started( fiber const&);
bool in_state_ready( fiber const&);
bool in_state_running( fiber const&);
- bool in_state_wait_for_join( fiber const&);
+ bool in_state_wait_for_fiber( fiber const&);
+ bool in_state_wait_for_object( fiber const&);
bool in_state_terminated( fiber const&);
void set_state_ready( fiber &);
void set_state_running( fiber &);
- void set_state_wait_for_join( fiber &);
+ void set_state_wait_for_fiber( fiber &);
+ void set_state_wait_for_object( fiber &);
void set_state_terminated( fiber &);
public:
@@ -971,16 +999,32 @@
virtual ~strategy();
virtual void add( fiber) = 0;
-
- virtual void yield( fiber::id const&) = 0;
-
- virtual void cancel( fiber::id const&) = 0;
virtual void join( fiber::id const&) = 0;
virtual void interrupt( fiber::id const&) = 0;
virtual void reschedule( fiber::id const&) = 0;
+
+ virtual void cancel( fiber::id const&) = 0;
+
+ virtual void yield( fiber::id const&) = 0;
+
+ virtual void register_object( object::id const&) = 0;
+
+ virtual void unregister_object( object::id const&) = 0;
+
+ virtual void wait_for_object( object::id const&) = 0;
+
+ virtual void object_notify_one( object::id const&) = 0;
+
+ virtual void object_notify_all( object::id const&) = 0;
+
+ virtual fiber release( fiber::id const&) = 0;
+
+ virtual void migrate( fiber) = 0;
+
+ virtual void detach_all() = 0;
virtual bool run() = 0;
@@ -1091,12 +1135,23 @@
[endsect]
-[section:in_state_wait_for_join Protected member function `in_state_wait_for_join( fiber const&)`]
+[section:in_state_wait_for_fiber Protected member function `in_state_wait_for_fiber( fiber const&)`]
- bool in_state_wait_for_join( fiber const&);
+ bool in_state_wait_for_fiber( fiber const&);
[variablelist
-[[Effects:] [Protected member function tests if the fiber is in the state `wait for join`.]]
+[[Effects:] [Protected member function tests if the fiber is in the state `wait for fiber`.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+
+[section:in_state_wait_for_object Protected member function `in_state_wait_for_object( fiber const&)`]
+
+ bool in_state_wait_for_object( fiber const&);
+
+[variablelist
+[[Effects:] [Protected member function tests if the fiber is in the state `wait for object`.]]
[[Throws:] [Nothing.]]
]
[endsect]
@@ -1135,12 +1190,23 @@
[endsect]
-[section:set_state_wait_for_join Protected member function `set_state_wait_for_join( fiber &)`]
+[section:set_state_wait_for_fiber Protected member function `set_state_wait_for_fiber( fiber &)`]
+
+ void set_state_wait_for_fiber( fiber &);
+
+[variablelist
+[[Effects:] [Protected member function sets the state of the fiber to `wait for fiber`.]]
+[[Throws:] [Nothing.]]
+]
+[endsect]
+
+
+[section:set_state_wait_for_object Protected member function `set_state_wait_for_object( fiber &)`]
- void set_state_wait_for_join( fiber &);
+ void set_state_wait_for_object( fiber &);
[variablelist
-[[Effects:] [Protected member function sets the state of the fiber to `wait for join`.]]
+[[Effects:] [Protected member function sets the state of the fiber to `wait for object`.]]
[[Throws:] [Nothing.]]
]
[endsect]
@@ -1179,6 +1245,51 @@
[endsect]
+[section:join Virtual member function `join( fiber::id const&)`]
+
+ virtual void join( fiber::id const&) = 0;
+
+[variablelist
+[[Precondition:] [Fiber belongs to this scheduler.]]
+[[Effects:] [The active fiber will yield until the fiber identified by the id has finished its
+execution or was interrupted.]]
+]
+[endsect]
+
+
+[section:interrupt Virtual member function `interrupt( fiber::id const&)`]
+
+ virtual void interrupt( fiber::id const&) = 0;
+
+[variablelist
+[[Precondition:] [Fiber belongs to this scheduler.]]
+[[Effects:] [The fiber identified by the id will be interrupted by its next execution.]]
+]
+[endsect]
+
+
+[section:reschedule Virtual member function `reschedule( fiber::id const&)`]
+
+ virtual void reschedule( fiber::id const&) = 0;
+
+[variablelist
+[[Precondition:] [Fiber belongs to this scheduler.]]
+[[Effects:] [The scheduling-algorithm will be applied uppon the fiber identified by the id again.]]
+]
+[endsect]
+
+
+[section:cancel Virtual member function `cancel( fiber::id const&)`]
+
+ virtual void cancel( fiber::id const&) = 0;
+
+[variablelist
+[[Precondition:] [Fiber belongs to this scheduler.]]
+[[Effects:] [The fiber with passed identifier will be stopped, e.g. removed from the run-queue.]]
+]
+[endsect]
+
+
[section:yield Virtual member function `yield( fiber::id const&)`]
virtual void yield( fiber::id const&) = 0;
@@ -1191,51 +1302,89 @@
[endsect]
-[section:cancel Virtual member function `cancel( fiber::id const&)`]
+[section:register_object Virtual member function `register_object( object::id const&)`]
- virtual void cancel( fiber::id const&) = 0;
+ virtual void register_object( object::id const&) = 0;
[variablelist
-[[Precondition:] [Fiber belongs to this scheduler.]]
-[[Effects:] [The fiber with passed identifier will be stopped, e.g. removed from the run-queue.]]
+[[Effects:] [Register the object (mutex, condition, event-variable).]]
]
[endsect]
-[section:join Virtual member function `join( fiber::id const&)`]
+[section:unregister_object Virtual member function `unregister_object( object::id const&)`]
- virtual void join( fiber::id const&) = 0;
+ virtual void unregister_object( object::id const&) = 0;
[variablelist
-[[Precondition:] [Fiber belongs to this scheduler.]]
-[[Effects:] [The active fiber will yield until the fiber identified by the id has finished its
-execution or was interrupted.]]
+[[Effects:] [Remove the object (mutex, condition, event-variable)i from the register.]]
]
[endsect]
-[section:interrupt Virtual member function `interrupt( fiber::id const&)`]
+[section:wait_for_object Virtual member function `wait_for_object( object::id const&)`]
- virtual void interrupt( fiber::id const&) = 0;
+ virtual void wait_for_object( object::id const&) = 0;
[variablelist
-[[Precondition:] [Fiber belongs to this scheduler.]]
-[[Effects:] [The fiber identified by the id will be interrupted by its next execution.]]
+[[Effects:] [The active fiber waits on object until notified.]]
]
[endsect]
-[section:reschedule Virtual member function `reschedule( fiber::id const&)`]
+[section:object_notify_one Virtual member function `object_notify_one( object::id const&)`]
- virtual void reschedule( fiber::id const&) = 0;
+ virtual void object_notify_one( object::id const&) = 0;
[variablelist
-[[Precondition:] [Fiber belongs to this scheduler.]]
-[[Effects:] [The scheduling-algorithm will be applied uppon the fiber identified by the id again.]]
+[[Effects:] [Notify one fiber waiting on the object. The fiber gets ready for scheduling.]]
+]
+[endsect]
+
+
+[section:object_notify_all Virtual member function `object_notify_all( object::id const&)`]
+
+ virtual void object_notify_all( object::id const&) = 0;
+
+[variablelist
+[[Effects:] [Notify all fibers waiting on the object. The fibers get ready for scheduling.]]
]
[endsect]
+[section:release Virtual member function `release( fiber::id const&)`]
+
+ virtual void release( fiber::id const&) = 0;
+
+[variablelist
+[[Postcondition:] [The fiber is not terminated or waits on fiber or object.]]
+[[Effects:] [Release fiber from scheduler.]]
+]
+[endsect]
+
+
+[section:migrate Virtual member function `migrate( fiber)`]
+
+ virtual void migrate( fiber) = 0;
+
+[variablelist
+[[Postcondition:] [The fiber is not already managed by scheduler.]]
+[[Effects:] [Adds fiber to scheduler.]]
+]
+[endsect]
+
+
+[section:detach_all Virtual member function `detach_all()`]
+
+ virtual void detach_all() = 0;
+
+[variablelist
+[[Effects:] [Detaches all managed fibers from this.]]
+]
+[endsect]
+
+
+
[section:run Virtual member function `run()`]
virtual bool run() = 0;
@@ -1269,6 +1418,13 @@
[endsect]
+[section:round_robin Class `round_robin`]
+
+The class `round_robin` dervives from __strategy__ and implements a simple round-robin schduling-axpglorithm.
+It does not respect priorities offibers.
+
+[endsect]
+
[endsect]
[endsect]
Modified: sandbox/fiber/libs/fiber/doc/fifos.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/fifos.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/fifos.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -8,9 +8,11 @@
[section:fifos (Un)Bounded fifos]
__boost_fiber__ provides a bounded and a unbounded fifo suitable to synchonize fibers via message passing.
-Both classes implement methods in order to be used by boost::intrusive_ptr.
- typedef boost::intrusive_ptr< boost::fibers::unbounded_fifo< int > > fifo_t;
+[note fifos are bound to a given __scheduler__ an can only be used by fibers
+managed by this scheduler.]
+
+ typedef boost::fibers::unbounded_fifo< int > fifo_t;
void send( fifo_t fifo)
{
@@ -27,7 +29,7 @@
}
boost::fibers::scheduler<> sched;
- fifo_t fifo( new boost::fibers::unbounded_fifo< int >() );
+ fifo_t fifo( sched);
sched.make_fiber( send, fifo);
sched.make_fiber( recv, fifo);
Modified: sandbox/fiber/libs/fiber/doc/mutexes.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/mutexes.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/mutexes.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -28,6 +28,9 @@
lock on a given instance of __mutex__ at any time. Multiple concurrent calls to __lock_ref__, __try_lock_ref__ and
__unlock_ref__ shall be permitted.
+[note __mutex__ is bound to a given __scheduler__ an can only be used by fibers
+managed by this scheduler.]
+
[endsect]
[endsect]
Modified: sandbox/fiber/libs/fiber/doc/overview.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/overview.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/overview.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -7,7 +7,7 @@
[section:overview Overview]
-__boost_fiber__ provides an framework utilizing lightweight threads of execution also known
+__boost_fiber__ provides an framework utilizing lightweight threads of execution - also known
as user-level/user-space threads or fibers (Win32 API). The API of the library is
modeled after __boost_thread__ and contains classes, functions to manage fibers and to synchronize
data between the fibers.
Modified: sandbox/fiber/libs/fiber/doc/todo.qbk
==============================================================================
--- sandbox/fiber/libs/fiber/doc/todo.qbk (original)
+++ sandbox/fiber/libs/fiber/doc/todo.qbk 2009-12-13 05:40:25 EST (Sun, 13 Dec 2009)
@@ -3,16 +3,10 @@
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:todo Todo]
-* provide a future and task class
-
-* provide a barrier class
-
* provide an scheduler which deals with priorities
* improve implementation of atomic-ops
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