From 350a26b27a8bda87c56fa092902eda12f745c1e7 Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 09:20:27 +0200 Subject: [PATCH 1/6] documentation: cycles of fiber switch - a context switch between fibers costs less than 100 cycles --- doc/overview.qbk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview.qbk b/doc/overview.qbk index 3129d3a5..79b21329 100644 --- a/doc/overview.qbk +++ b/doc/overview.qbk @@ -24,7 +24,7 @@ run (context switching). __boost_fiber__ internally uses __econtext__ from __boost_context__; the classes in this library manage, schedule and, when needed, synchronize those execution contexts. A context switch between threads usually costs thousands of CPU cycles on x86, -compared to a fiber switch with a few hundred cycles. +compared to a fiber switch with less than hundred cycles. A fiber can only run on a single thread at any point in time. In order to use the classes and functions described here, you can either include From 3fac431abca3568ae09588c6507e5d4be06f0a4a Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 09:51:58 +0200 Subject: [PATCH 2/6] documentation: this_fiber::yield() is a interruption point - this_fiber::yield() calls fiber_manager::yield() that calls fiber_manager::run() -> interruption point --- doc/fiber.qbk | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/fiber.qbk b/doc/fiber.qbk index 62f6ce00..c402c968 100644 --- a/doc/fiber.qbk +++ b/doc/fiber.qbk @@ -684,8 +684,8 @@ there are no guarantees about how soon after that it might resume.]] [variablelist [[Effects:] [Reliquishes execution control, allowing other fibers to run.]] [[Throws:] [__fiber_resource_error__ if an error occurs.]] -[[Note:] [`yield()` is ['not] an interruption point. A fiber that calls -`yield()` is not suspended: it is immediately passed to the scheduler as ready +[[Note:] [`yield()` is a interruption point. A fiber that calls +`yield()` is suspended, but it is immediately passed to the scheduler as ready to run.]] ] From 6740de676135e2640961a5de4b9dd573a0720473 Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 09:57:00 +0200 Subject: [PATCH 3/6] documentation: synch. objects are threadsafe per default - lib uses atomics to safely synchronize objects running in different threads - use BOOST_FIBERS_NO_ATOMICS to remove safety --- doc/overview.qbk | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/overview.qbk b/doc/overview.qbk index 79b21329..1432a2d4 100644 --- a/doc/overview.qbk +++ b/doc/overview.qbk @@ -68,10 +68,10 @@ A fiber launched on a particular thread will always run on that thread. A fiber can count on thread-local storage; however that storage will be shared among all fibers running on the same thread. -The fiber synchronization objects provided by this library will not, by -default, safely synchronize fibers running on different threads. However, they -can be coerced to provide that safety by building the library with -`BOOST_FIBERS_THREADSAFE` defined. Please see [link synchronization]. +The fiber synchronization objects provided by this library will, by default, +safely synchronize fibers running on different threads. However, they safety can +be removed (for performance) by building the library with +BOOST_FIBERS_NO_ATOMICS defined. Please see [link synchronization]. For fiber-local storage, please see __fsp__. From 1413406fab8329aa75add8c24b7cb082d9c222e0 Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 17:22:12 +0200 Subject: [PATCH 4/6] documentation: ready_fibers() returns zero if scheduler has no fibers --- doc/scheduling.qbk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/scheduling.qbk b/doc/scheduling.qbk index 09d5abbf..69de71d4 100644 --- a/doc/scheduling.qbk +++ b/doc/scheduling.qbk @@ -88,7 +88,7 @@ queue.]] virtual std::size_t ready_fibers() const noexcept = 0; [variablelist -[[Effects:] [Returns 0 if scheduling algorithm has fibers ready to run, +[[Effects:] [Returns 0 if scheduling algorithm has no fibers ready to run, otherwise nonzero.]] ] From 161f2a134c2fa6052496367d0e8cccfb6a617fde Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 18:20:31 +0200 Subject: [PATCH 5/6] documentation: default scheduler is not heap-allocated - round_robin, the default scheduler, is created at thread-creation as thread-local, local static --- doc/scheduling.qbk | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/scheduling.qbk b/doc/scheduling.qbk index 69de71d4..1305cbf7 100644 --- a/doc/scheduling.qbk +++ b/doc/scheduling.qbk @@ -20,10 +20,6 @@ customization point. (See [link custom].) Each thread has its own scheduler. By default, __boost_fiber__ implicitly instantiates [class_link round_robin] as the scheduler for each thread. -To prevent the library from heap-allocating the default scheduler for a given -thread, that thread must call [function_link set_scheduling_algorithm] before -any other __boost_fiber__ entry point. - You are explicitly permitted to code your own __algo__ subclass, and to pass it to [function_link set_scheduling_algorithm]. From b63f95758d6d5ababe8aac39ba74ad7ce4c1b6ec Mon Sep 17 00:00:00 2001 From: Oliver Kowalke Date: Tue, 28 Jul 2015 18:24:25 +0200 Subject: [PATCH 6/6] documentation: formating of code in scheduler.qbk --- doc/scheduling.qbk | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/doc/scheduling.qbk b/doc/scheduling.qbk index 1305cbf7..30e28d0d 100644 --- a/doc/scheduling.qbk +++ b/doc/scheduling.qbk @@ -41,8 +41,7 @@ fiber scheduler must implement. #include - struct sched_algorithm - { + struct sched_algorithm { virtual ~sched_algorithm() {} virtual void awakened( fiber_context *) = 0; @@ -95,8 +94,7 @@ This class implements __algo__, scheduling fibers in round-robin fashion. #include - class round_robin: public sched_algorithm - { + class round_robin: public sched_algorithm { virtual void awakened( fiber_context *); virtual fiber_context * pick_next(); @@ -139,10 +137,9 @@ A custom fiber properties class must be derived from `fiber_properties`. #include - class fiber_properties - { + class fiber_properties { public: - fiber_properties( back_ptr f ); + fiber_properties( back_ptr f); virtual ~fiber_properties() {} @@ -152,7 +149,7 @@ A custom fiber properties class must be derived from `fiber_properties`. [heading Constructor] - fiber_properties( back_ptr f ); + fiber_properties( back_ptr f); [variablelist [[Effects:] [Constructs base-class component of custom subclass.]] @@ -194,10 +191,9 @@ derived from [class_link fiber_properties]. #include template< typename PROPS > - struct sched_algorithm_with_properties - { + struct sched_algorithm_with_properties { // override this method instead of sched_algorithm::awakened() - virtual void awakened( fiber_context * f, PROPS& properties ) = 0; + virtual void awakened( fiber_context * f, PROPS & properties) = 0; virtual fiber_context * pick_next(); @@ -215,7 +211,7 @@ derived from [class_link fiber_properties]. [member_heading sched_algorithm_with_properties..awakened] - virtual void awakened( fiber_context * f, PROPS& properties ); + virtual void awakened( fiber_context * f, PROPS & properties); [variablelist [[Effects:] [Informs the scheduler that fiber `f` is ready to run, like @@ -286,10 +282,8 @@ implementations of [class_link fiber] methods.) #include - class fiber_context - { + class fiber_context { public: - fiber_context * nxt; static fiber_context * main_fiber();