[Boost-commit] svn:boost r53305 - sandbox/task/libs/task/doc

Subject: [Boost-commit] svn:boost r53305 - sandbox/task/libs/task/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-05-27 12:24:15

Author: olli
Date: 2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
New Revision: 53305
URL: http://svn.boost.org/trac/boost/changeset/53305

Log:
* documentation

Added:
   sandbox/task/libs/task/doc/default_pool.qbk   (contents, props changed)
   sandbox/task/libs/task/doc/processor_binding.qbk   (contents, props changed)
Text files modified: 
   sandbox/task/libs/task/doc/boost_task.qbk  |    10 ++++                                    
   sandbox/task/libs/task/doc/channel.qbk     |    25 ++++-------                             
   sandbox/task/libs/task/doc/pool.qbk        |    16 ++++--                                  
   sandbox/task/libs/task/doc/scheduler.qbk   |    12 +----                                   
   sandbox/task/libs/task/doc/static_pool.qbk |    81 +++++++++------------------------------ 
   5 files changed, 51 insertions(+), 93 deletions(-)

Modified: sandbox/task/libs/task/doc/boost_task.qbk
==============================================================================
--- sandbox/task/libs/task/doc/boost_task.qbk	(original)
+++ sandbox/task/libs/task/doc/boost_task.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -44,6 +44,8 @@
 [def __default_pool__ `boost::task::default_pool`]
 [def __dynamic_pool__ `boost::task::dynamic_pool`]
 [def __handle__ `boost::task::handle`]
+[def __hwm__ `boost::task::high_watermark`]
+[def __lwm__ `boost::task::low_watermark`]
 [def __new_thread__ `boost::task::new_thread`]
 [def __own_thread__ `boost::task::own_thread`]
 [def __task__ `boost::task::task`]
@@ -55,7 +57,7 @@
 [def __fn_delay__ `boost::this_task::delay()`]
 [def __fn_get_pool__ `boost::this_task::get_pool()`]
 [def __fn_tt_interrupt__ `boost::this_task::interrupt()`]
-[def __fn__interruption_requested__ `boost::this_thread::interruption_requested()`]
+[def __fn_interruption_requested__ `boost::this_thread::interruption_requested()`]
 [def __fn_make_task__ `boost::task::make_task()`]
 [def __fn_reschedule_until__ `boost::this_task::reschedule_until()`]
 [def __fn_runs_in_pool__ `boost::this_task::runs_in_pool()`]
@@ -65,17 +67,23 @@
 [def __fn_async__ `boost::task::async()`]
 [def __fn_default_pool__ `boost::task::default_pool()`]
 
+[def __fn_active__ `active()`]
+[def __fn_closed__ `close()`]
+[def __fn_empty__ `empty()`]
 [def __fn_get__ `get()`]
 [def __fn_get_id__ `get_id()`]
 [def __fn_get_future__ `get_future()`]
 [def __fn_has_value__ `has_value()`]
 [def __fn_has_exception__ `has_exception()`]
+[def __fn_idle__ `idle()`]
 [def __fn_interrupt__ `interrupt()`]
 [def __fn_interrupt_and_wait_for__ `interrupt_and_wait_for()`]
 [def __fn_interrupt_and_wait_until__ `interrupt_and_wait_until()`]
 [def __fn_interruption_requested__ `interruption_requested()`]
 [def __fn_is_ready__ `is_ready()`]
 [def __fn_operator__ `operator()()`]
+[def __fn_pending__ `pending()()`]
+[def __fn_size__ size()`]
 [def __fn_wait__ `wait()`]
 [def __fn_wait_for__ `wait_for()`]
 [def __fn_wait_until__ `wait_until()`]

Modified: sandbox/task/libs/task/doc/channel.qbk
==============================================================================
--- sandbox/task/libs/task/doc/channel.qbk	(original)
+++ sandbox/task/libs/task/doc/channel.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -8,28 +8,23 @@
 
 [section:channel Channel]
 
-The channel synchronizes the access between application threads (producer threads) submitting __actions__ to the pool and __worker_threads__ (consumer threads). The scheduling of __actions__ queued into the channel depends on channels scheduling policy.
-If the channel becomes empty all __worker_threads__ are set to sleep until a new __action__ is put in.
+The channel synchronizes the access between non-pool threads (application threads)  and __worker_threads__ and implements a queuing policy (limitation of queued _tasks__).
 
 
-[heading bounded channel]
+[heading __bounded_channel__]
 
-    template< typename SchedulingPolicy > class bounded_channel
-
-Contains a single lock in order to synchronize access to the queue. The number of pending __actions__ is limited in order to prevent resource exhaustion. For this purpose a high and low watermark has to be passed at construction.
-`boost::tp::high_watermark` sets the maximum of pending tasks. If this limited is reached all threads which submit a tasks will be set to sleep (blocked).
-`boost::tp::low_watermark` sets the threshold when blocked threads get woken up.
-If __hwm__ is equal to __lwm__ everytime a sleeping producer thread will be woken up and puts
-its task if one worker thread has taken a task from the channel.
-If __lwm__ is less than __hwm__ all sleeping producer threads will be woken up if
+__bounded_channel__ contains a single lock in order to synchronize access to the queue. The number of pending __tasks__ is limited in order to prevent resource exhaustion.
+For this purpose a high- and low-watermark has to be passed at construction.
+__hwm__ sets the maximum of pending tasks. If this limited is reached all threads which submit a task will be set to sleep (blocked). If it is equal to __lwm__ everytime a 
+sleeping producer thread will be woken up and puts its task if one worker thread has taken a task from the channel.
+__lwm__ sets the threshold when blocked threads get woken up. If it is less than __hwm__ all sleeping producer threads will be woken up if
 the amount of pending tasks reaches __lwm__.
 
 
-[heading unbounded channel]
-
-    template< typename SchedulingPolicy > class unbounded_channel
+[heading __unbounded_channel__]
 
-Contains a single lock in order to synchronize access to the queue. An unlimited number of __actions__ can be queued into this channel. The insertion of __actions__ will never block. If the channel becomes empty __worker_threads__ will be set to sleep until new __actions__ are inserted into the channel.
+__unbounded_channel__ contains a single lock in order to synchronize access to the queue. An unlimited number of __tasks__ can be queued into this channel.
+The insertion of an __task__ will never block. If the channel becomes empty __worker_threads__ will be set to sleep until new __tasks__ are enqueued.
 
 
 [endsect]

Added: sandbox/task/libs/task/doc/default_pool.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/default_pool.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -0,0 +1,17 @@
+[/
+          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
+]
+
+
+[section:default_pool Default pool]
+
+The free function `boost::tp::get_default_pool()` returns a reference to the default __threadpool__ instance. The default __threadpool__ is
+of type `boost::tp::pool< boost::tp::unbounded_channel< boost::tp::fifo > >` and will contain as many __worker_threads__ as 
+`boost::thread::hardware_concurrency()` returns. 
+
+
+[endsect]
+

Modified: sandbox/task/libs/task/doc/pool.qbk
==============================================================================
--- sandbox/task/libs/task/doc/pool.qbk	(original)
+++ sandbox/task/libs/task/doc/pool.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -8,11 +8,11 @@
 
 [section:pool Thread pool]
 
-A __thread_pool__ maintains a queue (or queues) of __work_items__ to be done, and a pool of __worker_threads__ which execute __work_items__ from the queue(s).
+Instead of creating a new thread and quickly throwing it away after the task is done, the overhead related to thread creation and destruction can be avoided by running the __work_items__ on a __thread_pool__ (reusing an existing __worker__thread__ instead).
 
-Instead of creating a new thread and quickly throwing it away after the task is done, the overhead related to thread creation and destruction can be avoided by running the __work_item__ on a __thread_pool__ (reusing an existing __worker__thread__ instead).
+A __thread_pool__ maintains a queue (or queues) of __work_items__ to be done, and a pool of __worker_threads__ which execute __work_items__ from the queue(s).
 
-__boost_task__ provides __fn_async__ with support of
+__boost_task__ provides __fn_async__ with support of executing an __task__ in __default_pool__ (using __fn_default_pool__):
 
 
 ``
@@ -31,7 +31,7 @@
         }
 ``
 
-executing a __task__ in __default_pool__ (using __fn_default_pool__)
+and a custom __thread_pool__ (passing pool instance as an argument to __fn_async__):
 
 
 ``
@@ -55,14 +55,18 @@
                 std::cout << h.get() << std::endl;
         }
 ``
+.
 
-and a custom __thread_pool__ (passing pool instance as an argument to __fn_async__).
-
+[important __tasks__ should not be too small (performance overhead dominates) and avoid blocking 
+__tasks__[footnote see [@http://www.ddj.com/go-parallel/article/showArticle.jhtml?articleID=216500409 
+'Use Thread Pools Correctly'], Herb Sutter].]
 
 [include static_pool.qbk]
 [include channel.qbk]
 [include scheduler.qbk]
 [include shutdown.qbk]
+[include default_pool.qbk]
+[include processor_binding.qbk]
 [include work_stealing.qbk]
 [include fork_join.qbk]
 

Added: sandbox/task/libs/task/doc/processor_binding.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/processor_binding.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -0,0 +1,22 @@
+[/
+          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
+]
+
+
+[section:processor_binding Processor binding]
+
+For some applications it is convenient to bind the worker threads of the pool to processors of the system. For this purpose BOOST_BIND_WORKER_TO_PROCESSORS must be defined. Without the poolsize in the construtor the __threadpool__ will contain as many
+__worker_threads__ as processors (== __hardware_concurrency__) are available and each __worker_thread__ is bound to one processor.
+
+	boost::tp::pool<
+      boost::tp::unbounded_channel< boost::tp::fifo >
+    > pool;
+
+The code above will create a pool with two __worker_threads__ on a dual core system (each bound to one core).
+
+
+[endsect]
+

Modified: sandbox/task/libs/task/doc/scheduler.qbk
==============================================================================
--- sandbox/task/libs/task/doc/scheduler.qbk	(original)
+++ sandbox/task/libs/task/doc/scheduler.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -8,31 +8,25 @@
 
 [section:scheduling Scheduling]
 
-The scheduling policy determines how __actions__ are scheduled inside the __channel__.
+The scheduling policy determines how __tasks__ are scheduled inside the __channel__.
 
 
 [heading fifo]
 
-    struct fifo
-
-First inserted pending __action__ get taken first.
+First inserted pending __task__ gets taken first.
 
 
 [heading priority]
 
-    template< typename Attr, typename Ord = std::less< Attr > > struct priority
-
 Each pending task is associated with a priority attribute which is used for ordering __actions__.
 
 
 [heading smart]
 
-    template< typename Attr, typename Ord, typename Enq, typename Deq > struct smart
-
 Each pending __actions__ is associated with an attribute. The scheduler gets an put- and take-policy
 as template arguments. The corresponding policy get applied for each insertion and removal.
 
-__boost_threadpool__ provides ['boost::tp::replace_oldest] as put policy and ['boost::tp::take_oldest] as take
+__boost_task__ provides ['boost::tp::replace_oldest] as put policy and ['boost::tp::take_oldest] as take
 policy. Both policies allow the replacement of old __actions__ in the scheduler by new ones.
 
     // creates a pool with unbounded channel

Modified: sandbox/task/libs/task/doc/static_pool.qbk
==============================================================================
--- sandbox/task/libs/task/doc/static_pool.qbk	(original)
+++ sandbox/task/libs/task/doc/static_pool.qbk	2009-05-27 12:24:13 EDT (Wed, 27 May 2009)
@@ -8,76 +8,33 @@
 
 [section:static_pool __static_pool__]
 
-The first template argument specifies the channel type and the scheduling policy.
+__boost_task__ provides __static_pool__ - which contains an fixed set of pre-forked __worker_threads__ (the size of the pool doesn't change during its lifetime).
 
-    boost::tp::pool<
-      boost::tp::unbounded_channel< boost::tp::fifo >
-    > pool(
-      boost::tp::poolsize( 6),
-      boost::posix_time::posix_time::milliseconds( 50),
-      boost::tp::scanns(10) );
 
-In the example above a __threadpool__ is created with a __unbounded_channel__, scheduling __actions__ in ['FIFO] order. The pool contains six __worker_threads__ going to sleep for 50 millisec after 10 iterations without geting an __action__ from the __global_queue__, from its local __worker_queue__ or local queues of other __worker_threads__.
+``
+	boost::task::_static_pool<			// pool type
+		boost::task::unbounded_channel<		// queuing policy (unbounded_channel, bounded_channel)
+			boost::task::fifo		// scheduling policy (fifo, priority, smart)
+		>
+	> pool(
+		boost::task::poolsize( 6),				// pool with 6 pre-forked worker-threads
+		boost::posix_time::posix_time::milliseconds( 50),	// time to sleep if no work-item available
+		boost::task::scanns( 10) );				// iterations over local-queues before sleep
+``
 
-    boost::tp::pool<
-      boost::tp::bounded_channel< boost::tp::priority < int > >
-    > pool(
-      boost::tp::poolsize( 10),
-      boost::tp::high_watermark( 10),
-      boost::tp::low_watermark( 5) );
 
-This pool uses a __bounded_channel__ which schedules __actions__ by integer atrributes. A maximum of 10 __actions__ can be queued in the __global_queue__ without blocking the inserting thread.
+The first argument of the constructor specifies how many __worker_threads__ the pool will contain. The second
+and third argument are used by the link_work_stealing[__work_stealing__] algorithm.
 
+[note If __bounded_channel__ is used as queuing policy the constructor has two additional arguments (link_channel[hight- and lower-watermark]). ]
 
-[heading Shutdown]
+__static_pool__ provides functionality to check the status of the pool - __fn_closed__ returns true when the pool was shutdown and __fn_active__ as well as __fn__idle__ returning how many __worker_threads__ 
+are active (executing a task) or idle. The size of the pool can be accessed over __fn_size__.
 
-If `boost::tp::pool< Channel >::shutdown()` is called - the the pool is set closed and all __worker_threads__ are joined until all pending __actions__ are processed. No futher __actions__ can be submitted by application threads.
+For infomational pruposes __fn_empty__ and __fn_pending__ can be used in order to know if the global task-queue is empty or how many __tasks__ are waiting for execution.
+__fn_clear__ removes all __tasks__ from the global-queue.
 
-[note The deconstructor calls `boost::tp::pool< Channel >::shutdown()` if the pool was not shutdown yet.]
-
-    boost::tp::pool<
-      boost::tp::unbounded_channel< boost::tp::fifo >
-    > pool( boost::tp::poolsize( 1) );
-
-    boost::tp::task< int > t1(
-      pool.submit(
-      boost::bind(
-        fibonacci_fn,
-        10) ) );
-    boost::tp::task< int > t2(
-      pool.submit(
-        boost::bind(
-          fibonacci_fn,
-          10) ) );
-
-    pool.shutdown();
-
-    std::cout << t1.result().get() << std::endl; // 55
-    std::cout << t2.result().get() << std::endl; // 55
-
-[heading Shutdown immediatly]
-The function `boost::tp::pool< Channel >::shutdown_now()` closes the pool, interrupts and then joins all __worker_threads__. All pending (unprocessed) __actions__ will be returned.
-
-[important Pending __actions__ in the local __worker_queues__ are not returned if `boost::tp::pool< Channel >::shutdown_now()` was called.]
-
-
-[heading Default pool]
-
-The free function `boost::tp::get_default_pool()` returns a reference to the default __threadpool__ instance. The default __threadpool__ is
-of type `boost::tp::pool< boost::tp::unbounded_channel< boost::tp::fifo > >` and will contain as many __worker_threads__ as 
-`boost::thread::hardware_concurrency()` returns. 
-
-
-[heading Processor binding]
-
-For some applications it is convenient to bind the worker threads of the pool to processors of the system. For this purpose BOOST_BIND_WORKER_TO_PROCESSORS must be defined. Without the poolsize in the construtor the __threadpool__ will contain as many
-__worker_threads__ as processors (== __hardware_concurrency__) are available and each __worker_thread__ is bound to one processor.
-
-	boost::tp::pool<
-      boost::tp::unbounded_channel< boost::tp::fifo >
-    > pool;
-
-The code above will create a pool with two __worker_threads__ on a dual core system (each bound to one core).
+[note __fn_pending__ does not count __tasks__ in the local-queues of the __worker_threads__.]
 
 
 [endsect]