|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r53034 - sandbox/task/libs/task/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-05-15 17:31:29
Author: olli
Date: 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
New Revision: 53034
URL: http://svn.boost.org/trac/boost/changeset/53034
Log:
* updating documentation
Added:
sandbox/task/libs/task/doc/as_sub_task.qbk (contents, props changed)
sandbox/task/libs/task/doc/async_completion_token.qbk (contents, props changed)
sandbox/task/libs/task/doc/async_executor.qbk (contents, props changed)
sandbox/task/libs/task/doc/description.qbk (contents, props changed)
sandbox/task/libs/task/doc/handle.qbk (contents, props changed)
sandbox/task/libs/task/doc/new_thread.qbk (contents, props changed)
sandbox/task/libs/task/doc/own_thread.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_exceptions.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_meta.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_poolsize.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_stacksize.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_static_pool.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_task.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_this_task.qbk (contents, props changed)
sandbox/task/libs/task/doc/ref_watermark.qbk (contents, props changed)
Removed:
sandbox/task/libs/task/doc/exceptions_ref.qbk
sandbox/task/libs/task/doc/meta_ref.qbk
sandbox/task/libs/task/doc/pool_ref.qbk
sandbox/task/libs/task/doc/poolsize_ref.qbk
sandbox/task/libs/task/doc/scanns_ref.qbk
sandbox/task/libs/task/doc/stacksize_ref.qbk
sandbox/task/libs/task/doc/task_ref.qbk
sandbox/task/libs/task/doc/this_task_ref.qbk
sandbox/task/libs/task/doc/watermark_ref.qbk
Text files modified:
sandbox/task/libs/task/doc/boost_task.qbk | 80 ++++++++++++++---------
sandbox/task/libs/task/doc/introduction.qbk | 135 +++++++++++++++++++++++----------------
sandbox/task/libs/task/doc/overview.qbk | 15 +--
sandbox/task/libs/task/doc/pool.qbk | 2
sandbox/task/libs/task/doc/task.qbk | 53 +++++++--------
5 files changed, 161 insertions(+), 124 deletions(-)
Added: sandbox/task/libs/task/doc/as_sub_task.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/as_sub_task.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1 @@
+
Added: sandbox/task/libs/task/doc/async_completion_token.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/async_completion_token.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,13 @@
+[/
+ 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:async_completion_token Asynchronous completion token]
+
+[include handle.qbk]
+
+[endsect]
Added: sandbox/task/libs/task/doc/async_executor.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/async_executor.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,16 @@
+[/
+ 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:async_executor Asynchronous executor]
+
+[include own_thread.qbk]
+[include new_thread.qbk]
+[include pool.qbk]
+[include as_sub_task.qbk]
+
+[endsect]
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-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -24,58 +24,76 @@
[def __boost_thread__ [@http://www.boost.org/libs/thread [*Boost.Thread]]]
[def __boost_future__ [@http://www.justsoftwaresolutions.co.uk/threading/updated-implementation-of-c++-futures-3.html [*Boost.Future]]]
-[template link_coop_task[link_text] [link boost_task.cooperative_task [link_text]]]
-[template link_channel[link_text] [link boost_task.channel [link_text]]]
-[template link_forkjoin[link_text] [link boost_task.forkjoin [link_text]]]
+[template link_act[link_text] [link boost_task.async_completion_token [link_text]]]
+[template link_ae[link_text] [link boost_task.async_executor [link_text]]]
+[template link_coop_task[link_text] [link boost_task.task.cooperative_task [link_text]]]
+[template link_channel[link_text] [link boost_task.pool.channel [link_text]]]
+[template link_forkjoin[link_text] [link boost_task.pool.forkjoin [link_text]]]
+[template link_handle[link_text] [link boost_task.async_completion_token.handle [link_text]]]
+[template link_pool[link_text] [link boost_task.pool [link_text]]]
[template link_task[link_text] [link boost_task.task [link_text]]]
-[template link_ws[link_text] [link boost_task.pool.work_stealing [link_text]]]
+[template link_work_stealing[link_text] [link boost_task.pool.work_stealing [link_text]]]
-[def __hardware_concurrency__ `boost::thread::hardware_concurrency()`]
[def __thread__ `boost::thread`]
-[def __as_sub_task__ `as_sub_task`]
-[def __bounded_channel__ `bounded_channel`]
-[def __default_pool__ `default_pool`]
-[def __duration__ `Duration`]
-[def __handle__ `handle`]
-[def __new_thread__ `new_thread`]
-[def __own_thread__ `own_thread`]
-[def __task__ `task`]
-[def __system_time__ `system_time`]
-[def __unbounded_channel__ `unbounded_channel`]
-
-[def __fn_async__ `async()`]
-[def __fn_default__pool__ `default_pool()`]
-[def __fn_delay__ `delay()`]
+[def __hardware_concurrency__ `boost::thread::hardware_concurrency()`]
+
+[def __as_sub_task__ `boost::task::as_sub_task`]
+[def __bounded_channel__ `boost::task::bounded_channel`]
+[def __default_pool__ `boost::task::default_pool`]
+[def __handle__ `boost::task::handle`]
+[def __new_thread__ `boost::task::new_thread`]
+[def __own_thread__ `boost::task::own_thread`]
+[def __task__ `boost::task::task`]
+[def __static_pool__ `boost::task::static_pool`]
+[def __system_time__ `boost::task::system_time`]
+[def __unbounded_channel__ `boost::task::unbounded_channel`]
+
+[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_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()`]
+[def __fn_worker_id__ `boost::this_task::worker_id()`]
+[def __fn_yield__ `boost::this_task::yield()`]
+
+[def __fn_async__ `boost::task::async()`]
+[def __fn_default_pool__ `boost::task::default_pool()`]
+
[def __fn_get__ `get()`]
[def __fn_get_id__ `get_id()`]
-[def __fn_get_pool__ `get_pool()`]
[def __fn_has_value__ `has_value()`]
[def __fn_has_exception__ `has_exception()`]
[def __fn_interrupt__ `interrupt()`]
[def __fn_interrupt_and_wait__ `interrupt_and_wait()`]
[def __fn_interruption_requested__ `interruption_requested()`]
[def __fn_is_ready__ `is_ready()`]
-[def __fn_make_task__ `make_task()`]
-[def __fn_reschedule_until__ `reschedule_until()`]
-[def __fn_runs_in_pool__ `runs_in_pool()`]
[def __fn_wait__ `wait()`]
-[def __fn_worker_id__ `worker_id()`]
-[def __fn_yield__ `yield()`]
+[def __fn_wait_for__ `wait_for()`]
+[def __fn_wait_until__ `wait_until()`]
[def __act__ `asynchronous-completion-token`]
[def __ae__ `asynchronous-executor`]
[def __aes__ `asynchronous-executors`]
[def __blocked__ ['blocked]]
+[def __callable__ ['callable]]
+[def __coop_task__ `cooperative task`]
+[def __duration__ `Duration`]
[def __fork_join__ ['fork/join]]
-[def __interruption_point__ ['interruption point]]
-[def __task_id__ ['task id]]
-[def __thread_pool__ ['thread pool]]
-[def __work_stealing__ ['work stealing]]
-[def __worker_queue__ ['worker queue]]
-[def __worker_thread__ ['worker thread]]
+[def __interruption_point__ ['interruption-point]]
+[def __task_id__ ['task-id]]
+[def __thread_pool__ ['thread-pool]]
+[def __thread_pools__ ['thread-pools]]
+[def __sub_task__ ['sub-task]]
+[def __sub_tasks__ ['sub-tasks]]
+[def __work_stealing__ ['work-stealing]]
+[def __worker_queue__ ['worker-queue]]
+[def __worker_thread__ ['worker-thread]]
+[def __worker_threads__ ['worker-threads]]
[include overview.qbk]
+[include description.qbk]
[include reference.qbk]
[include appendices.qbk]
Added: sandbox/task/libs/task/doc/description.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/description.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,15 @@
+[/
+ 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:description Description]
+
+[include task.qbk]
+[include async_completion_token.qbk]
+[include async_executor.qbk]
+
+[endsect]
Deleted: sandbox/task/libs/task/doc/exceptions_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/exceptions_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,126 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:invalid_poolsize Class `invalid_poolsize`]
-
- #include <boost/tp/exceptions.hpp>
-
- class invalid_poolsize
- : public std::invalid_argument
- {
- public:
- invalid_poolsize( std::string const& msg);
- };
-
-[section:constructor Constructor]
-
- invalid_poolsize( std::string const& msg);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::invalid_poolsize` instance.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:invalid_scanns Class `invalid_scanns`]
-
- #include <boost/tp/exceptions.hpp>
-
- class invalid_scanns
- : public std::invalid_argument
- {
- public:
- invalid_scanns( std::string const& msg);
- };
-
-[section:constructor Constructor]
-
- invalid_scanns( std::string const& msg);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::invalid_scanns` instance.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:invalid_timeduration Class `invalid_timeduration`]
-
- #include <boost/tp/exceptions.hpp>
-
- class invalid_timeduration
- : public std::invalid_argument
- {
- public:
- invalid_timeduration( std::string const& msg);
- };
-
-[section:constructor Constructor]
-
- invalid_timeduration( std::string const& msg);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::invalid_timeduration` instance.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:invalid_watermark Class `invalid_watermark`]
-
- #include <boost/tp/exceptions.hpp>
-
- class invalid_watermark
- : public std::invalid_argument
- {
- public:
- invalid_watermark( std::string const& msg);
- };
-
-[section:constructor Constructor]
-
- invalid_watermark( std::string const& msg);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::invalid_watermark` instance.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:task_rejected Class `task_rejected`]
-
- #include <boost/tp/exceptions.hpp>
-
- class task_rejected
- : public std::runtime_error
- {
- public:
- task_rejected( std::string const& msg);
- };
-
-[section:constructor Constructor]
-
- task_rejected( std::string const& msg);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::task_rejected` instance.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
Added: sandbox/task/libs/task/doc/handle.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/handle.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1 @@
+
Modified: sandbox/task/libs/task/doc/introduction.qbk
==============================================================================
--- sandbox/task/libs/task/doc/introduction.qbk (original)
+++ sandbox/task/libs/task/doc/introduction.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -9,37 +9,70 @@
[section:motivation Motivation]
To speed-up computer-bound work and/or increase the computation-throughput is a common motivation for parallelizing a program.
-Especially for interactive applications that have to process user input while perfoming some background tasks responsivness
-is very important.
-The ongoing evolution of many-core architectures support this naturaly by requiring partitioning the program into smaller chunks that can run in parallel.
-The code can scale as the hardware gets better without changing the code (and achieving desired load balancing).
+Especially for interactive applications that have to process user input while performing some background tasks responsivness is very important.
+Parallelizing a program requires partitioning the program into smaller chunks that can run in parallel. The code can scale as the hardware
+gets better without changing the code.
+
+The evolution from one-core to many-core architectures and the usage of threads (of course processes fit too) support this paradigm.
[note
- ["You can have multithreading on a single core machine, but you can only have parallelism on a multi core machine ... .
- [footnote more to read at [@http://www.danielmoth.com/Blog/2008/11/threadingconcurrency-vs-parallelism.html]] ] -- Daniel Moth
+ ["You can have multithreading on a single core machine, but you can only have parallelism on a multi core machine ... .] -- Daniel Moth
+ [footnote more to read at Daniel's [@http://www.danielmoth.com/Blog/2008/11/threadingconcurrency-vs-parallelism.html [blog]]]
]
__boost_task__ provides a framework to utilize the available hardware and provide a way for efficient asynchronous processing of time consuming operations.
+The framework provides some link_ae[__aes__], like __new_thread__, in order to execute the task asynchronously in another execution context (__boost_task__
+uses preemptible threads for this purpose).
+
+ void print( std::string const& msg)
+ { printf("%s\n", msg.c_str() ); }
+
+ void main()
+ {
+ boost::task::async( // dispatchs task
+ boost::task::new_thread(), // asynchronous executor
+ boost::task::make_task( // task, to be executed asynchronously
+ print,
+ "Hello World!") ) );
+ }
-The framework provides some __aes__, like __new_thread__, in order to launch __task__ in a new thread:
+In order to manage the task __assync__ returns a handle __handle__ (associated with the submitted task). It functions as a __act__ - that means it transfers
+the result of the execution back to the caller thread.
std::string echo( std::string const& msg)
{ return msg; }
void main()
{
- boost::task::handle< std::string > h(
- boost::task::async(
- boost::task::new_thread(),
- boost::task::make_task(
+ boost::task::handle< std::string > h( // get handle associated with the task
+ boost::task::async(
+ boost::task::new_thread(), // asynchronous executor
+ boost::task::make_task( // task, to be executed asynchronously
echo,
"Hello World!") ) );
- std::cout << h.get() << std::endl;
+ std::cout << h.get() << std::endl; // wait until task is finished and return the result
+ }
+
+The task can also be interrupted via __handle__ if it is a so-called link_coop_task[__coop_task__].
+
+ void long_running( boost::posix_time::time_duration const& rel_time)
+ { boost::this_thread::sleep( rel_time);
+
+ void main()
+ {
+ boost::task::handle< std::string > h( // get handle associated with the task
+ boost::task::async(
+ boost::task::new_thread(), // asynchronous executor
+ boost::task::make_task( // long runing task, to be executed asynchronously
+ long_running,
+ boost::posix_time::millisec( 500) ) ) );
+ h.interrupt(); // interrupt execution of task
+ std::cout << h.get() << std::endl; // wait until task is finished, will throw an exeception
}
-__handle__ manages the __task__ and allows to transfer the result to the caller thread.
-With __runs_in_pool__ the task can detect if it is running inside a __thread_pool__ (executed by a __worker_thread__) at runtime.
+Beside __new_thread__ (which creates a new task for each submitted task) __boost_task__ provides link_pool[__thread_pools__] to prevent the overhead of thread creation
+and destruction for each task. __default_pool__ submitts the tasks to the default __thread_pool__ which contains a fixed number of pre-spawned __worker_threads__ (custom __thread_pools__ are supported too).
long serial_fib( long n)
{
@@ -52,59 +85,49 @@
if ( n < cutof) return serial_fib( n);
else
{
- boost::task::handle< long > h1, h2;
- if ( boost::this_task::runs_in_pool() )
- {
- // task is executed inside a thread-pool
- // the sub-tasks are submitted to the thread-local
- // worker-queue for speed improvments
- h1 = boost::task::async(
- boost::this_task::as_sub_task(),
- boost::task::make_task(
- parallel_fib,
- n - 1,
- cutof) );
- h2 = boost::task::async(
- boost::this_task::as_sub_task(),
- boost::task::make_task(
- parallel_fib,
- n - 2,
- cutof) );
- }
- else
- {
- // task is not running inside a thread-pool
- // the sub-tasks are executed in new threads
- h1 = boost::task::async(
- boost::this_task::new_thread(),
- tsk::make_task(
- parallel_fib,
- n - 1,
- cutof) );
- h2 = boost::task::async(
- boost::this_task::new_thread(),
- boost::task::make_task(
- parallel_fib,
- n - 2,
- cutof) );
- }
+ // submit a sub-task to pool calculating fibonacci(n-1)
+ h1 = boost::task::async(
+ boost::this_task::get_pool(),
+ boost::task::make_task(
+ parallel_fib,
+ n - 1,
+ cutof) );
+ // submit a sub-task to pool calculating fibonacci(n-2)
+ h2 = boost::task::async(
+ boost::this_task::get_pool(),
+ boost::task::make_task(
+ parallel_fib,
+ n - 2,
+ cutof) );
+ // calculate fibonacci(n) from the results of both sub-tasks
return h1.get() + h2.get();
}
}
void main()
{
- boost::task::handle< long > h(
+ boost::task::handle< long > h( // handle for fibonacci calculation
boost::task::async(
- // boost::task::new_thread(),
- boost::task::default_pool(),
- boost::task::make_task(
- parallel_fib,
+ boost::task::default_pool(), // access the default thread-pool
+ boost::task::make_task( // calculate fibonacci number 10
+ parallel_fib, // for numbers < 5 do inline recursive calculation
10,
- 5) ) );
+ 5) ) );
std::cout << h.get() << std::endl;
}
};
+With function __fn_runs_in_pool__ a task can detect if it is executed inside a __thread_pool__.
+__sub_tasks__ arecreated by __as_sub_task__. Where the __sub_task__ is executed by a new thread if the parent task
+is not executed inside a __thread_pool__. In the other case the __sub_task__ is put into the local __worker_queue__
+which enables link_work_stealing[__work_stealing__] and link_forkjoin[inline execution] of tasks.
+
+ boost::task::async(
+ boost::task::as_sub_task(), // sub-task executed in a new thread or inside
+ boost::task::make_task( // the thread-pool depending upon the parent
+ parallel_fib, // task is executed inside a thread-pool or not
+ 10,
+ 5) ) );
+
[endsect]
Deleted: sandbox/task/libs/task/doc/meta_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/meta_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,36 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:has_priority Meta function `has_priority`]
-
- #include <boost/tp/info.hpp>
-
- template< typename Pool >
- struct has_priority
- :
- public mpl::bool_<
- is_same<
- detail::has_priority,
- typename Pool::scheduler_type::priority_tag_type
- >::value
- >
- {};
-
-[endsect]
-
-
-[section:priority_type Meta function `priority_type`]
-
- #include <boost/tp/info.hpp>
-
- template< typename Pool >
- struct priority_type
- {
- typedef typename Pool::scheduler_type::attribute_type type;
- };
-
-[endsect]
Added: sandbox/task/libs/task/doc/new_thread.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/new_thread.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1 @@
+
Modified: sandbox/task/libs/task/doc/overview.qbk
==============================================================================
--- sandbox/task/libs/task/doc/overview.qbk (original)
+++ sandbox/task/libs/task/doc/overview.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -8,11 +8,9 @@
[section:overview Overview]
-[heading Description]
+__boost_task__ provides an framework for parallel execution of tasks (a task is a small unit of code that can be executed independently).
-__boost_task__ provides an abstraction for parallel execution of tasks (a task is a small unit of code that can be executed independently).
-
-* __task__, representing fine-grained work-item:
+* __task__, __callable__ representing a fine-grained work-item:
* get_id() returning an identifier
* operator() to execute the fine-grained work-item
* get_future() providing an __act__ in order to pass the result (values, exceptions) back to initiator
@@ -25,13 +23,13 @@
* is_ready() test if task was executed
* wait(), wait_for() and wait_until() block until task is executed and the result is set
-* __async__, execute a task on behalf of __aes__
+* __async__, executes a task on behalf of __aes__
* __ae__ models:
* __own_thread__: executes task in current thread.
* __new_thread__: executes task in a newly created thread (thread will be destroyed after)
* __default_pool__: task gets executed by a __worker_thread__ of the default __thread_pool__
- * __as_sub_task__: executes task in newly created thread or in a pool depending on whether current task is already executed in a pool
+ * __as_sub_task__: executes task in newly created thread or in a pool of __worker_threads__ depending on whether current task is already executed in a pool
* custom pool: task gets executed by a __worker_thread__ of a custom __thread_pool__
@@ -58,10 +56,9 @@
[heading Tested Platforms]
__boost_task__ has been tested on the following platforms and compilers:
-* Linux 2.6.29.2 (amd64), GCC 4.3.2
-* Linux 2.6.23.9 (i386), GCC 4.2.4
+* Linux 2.6.29.2 (amd64), GCC 4.3.3
* FreeBSD 7.2 (amd64), GCC 4.2.1
-* OpenSolaris 0811 (amd64), GCC 4.2.1
+* OpenSolaris 0811 (amd64), SUN
* Windows XP Professional (i386), MSVC 9.0
Added: sandbox/task/libs/task/doc/own_thread.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/own_thread.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1 @@
+
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-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -7,6 +7,8 @@
[section:pool Pool]
+It is fairly common for one work item to need to wait for the execution of another work item to complete. If the second work item has not yet begun executing, it will be sitting in the queue waiting for a worker thread to pick it up. It is possible that there are no available worker threads – maybe they’re all waiting for other work items to complete! This can cause deadlock in the worst case, and very slow execution in the best, as the thread pool may be slow to add more worker threads to pick up these work items. Task.Wait, on the other hand, knows it’s waiting for another task, and is tightly integrated with the thread pool such that it is able to determine whether the task has started executing, and if not it executes it immediately, in-line on the current thread. This greatly improves performance and eliminates the possibility of deadlock in this situation.
+
The CLR thread pool has the correct internal logic and a simple interface (QueueUserWorkItem) for scheduling work items to be executed by the threads it manages. This appears to be the answer to achieving fine grained parallelism.
A thread pool basically has two functions: It maintains a queue (or queues) of work to be done, and a collection of threads which execute work from the queue(s). So designing a thread pool really comes down to a) finding ways to enqueue and dequeue work items very quickly (to keep the overhead of using the thread pool to a minimum) and b) developing an algorithm for choosing an optimal number of threads to service the queues.
Deleted: sandbox/task/libs/task/doc/pool_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/pool_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,353 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:pool Class template `pool`]
-
- #include <boost/tp/pool.hpp>
-
- template< typename Channel >
- class pool
- : private noncopyable
- {
- public:
- explicit pool(
- poolsize const& psize,
- posix_time::time_duration const& asleep = posix_time::microseconds( 10),
- scanns const& scns = scanns( 20) );
-
- explicit pool(
- poolsize const& psize,
- high_watermark const& hwm,
- low_watermark const& lwm,
- posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
- scanns const& scns = scanns( 20) );
-
-
- explicit pool(
- posix_time::time_duration const& asleep = posix_time::microseconds( 10),
- scanns const& scns = scanns( 20) );
-
- explicit pool(
- high_watermark const& hwm,
- low_watermark const& lwm,
- posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
- scanns const& scns = scanns( 20) );
-
- ~pool();
-
- std::size_t size();
- std::size_t active();
- std::size_t idle();
-
- void shutdown();
- const std::vector< callable > shutdown_now();
-
- bool closed();
- void clear();
- bool empty();
- std::size_t pending();
-
- const std::size_t upper_bound();
- void upper_bound( high_watermark const& hwm);
- const std::size_t lower_bound();
- void lower_bound( low_watermark const& lwm);
-
- template< typename Act >
- task< typename result_of< Act() >::type > submit( Act const& act);
-
- template< typename Act, typename Attr >
- task< typename result_of< Act() >::type > submit(
- Act const& act,
- Attr const& attr);
- };
-
- pool< unbounded_channel< fifo > > & get_default_pool();
-
- template< typename Act >
- task< R > launch_in_pool( Act const& act);
-
-[section:constructor_unbounded_channel_hw Constructor (unbounded channel)]
-
- explicit pool(
- posix_time::time_duration const& asleep = posix_time::microseconds( 10),
- scanns const& scns = scanns( 20) );
-
-[variablelist
-[[Preconditions:] [Operating system provides functionality for processor pining.]]
-[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. For each processor a worker-thread is created and each worker-thread is pined exactly to one processor.]]
-[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`]]
-[[Notes:] [Constructor has to be called if a __unbounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:constructor_unbounded_channel Constructor (unbounded channel)]
-
- explicit pool(
- poolsize const& psize,
- posix_time::time_duration const& asleep = posix_time::microseconds( 10),
- scanns const& scns = scanns( 20) );
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. Pool contains psize worker-threads.]]
-[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`]]
-[[Notes:] [Constructor has to be called if a __unbounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:constructor_bounded_channel_hw Constructor (bounded channel)]
-
- explicit pool(
- high_watermark const& hwm,
- low_watermark const& lwm,
- posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
- scanns const& scns = scanns( 20) );
-
-[variablelist
-[[Preconditions:] [Operating system provides functionality for processor pining.]]
-[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. For each processor a worker-thread is created and each worker-thread is pined exactly to one processor.]]
-[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`, `boost::tp::invalid_watermark`]]
-[[Notes:] [Constructor has to be called if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:constructor_bounded_channel Constructor (bounded channel)]
-
- explicit pool(
- poolsize const& psize,
- high_watermark const& hwm,
- low_watermark const& lwm,
- posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
- scanns const& scns = scanns( 20) );
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. Pool contains psize worker-threads.]]
-[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`, `boost::tp::invalid_watermark`]]
-[[Notes:] [Constructor has to be called if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:destructor Destructor]
-
- ~pool();
-
-[variablelist
-[[Effects:] [Calls `boost::tp::pool< Channel >::shutdown()` if not yet called.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:size Member function `size()`]
-
- std::size_t size();
-
-[variablelist
-[[Effects:] [Returns how many worker threads are running in the pool.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:active Member function `active()`]
-
- std::size_t active();
-
-[variablelist
-[[Effects:] [Returns how many worker threads are active (executing an __action__).]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:idle Member function `idle()`]
-
- std::size_t idle();
-
-[variablelist
-[[Effects:] [Returns how many worker threads are idle (not executing an __action__).]]
-[[Throws:] [Nothing]]
-[[Notes:] [The value is the difference of `size()` and `active()`]]
-]
-[endsect]
-
-
-[section:shutdown Member function `shutdown()`]
-
- void shutdown();
-
-[variablelist
-[[Effects:] [Deactivates the channel and joins all worker threads. The pool is closed.]]
-[[Throws:] [Nothing]]
-[[Notes:] [All pending __actions__ are processed.]]
-]
-[endsect]
-
-
-[section:shutdown_now Member function `shutdown_now()`]
-
- const std::vector< callable > shutdown_now();
-
-[variablelist
-[[Effects:] [Deactivates the channel, send interruption request to all worker threads and joins them. The pool is closed.]]
-[[Throws:] [Nothing]]
-[[Notes:] [Pending __actions__ are not processed but returned.]]
-]
-[endsect]
-
-
-[section:losed Member function `closed()`]
-
- bool closed();
-
-[variablelist
-[[Effects:] [Queries if the pool is closed (pool is shutdown).]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:clear Member function `clear()`]
-
- void clear();
-
-[variablelist
-[[Effects:] [Removes all pending __actions__ from the __channel__.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:empty Member function `empty()`]
-
- bool empty();
-
-[variablelist
-[[Effects:] [Queries if the __channel__ is empty.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:pending Member function `pending()`]
-
- std::size_t pending();
-
-[variablelist
-[[Effects:] [Queries how many __actions__ are pending in the __channel__.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:get_upper_bound Member function `upper_bound()`]
-
- std::size_t upper_bound();
-
-[variablelist
-[[Preconditions:] [Channel is of type __bounded_channel__.]]
-[[Effects:] [Returns the upper bound of the __bounded_channel__.]]
-[[Throws:] [Nothing]]
-[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:set_upper_bound Member function `upper_bound( high_watermark const& hwm)`]
-
- void upper_bound( high_watermark const& hwm);
-
-[variablelist
-[[Preconditions:] [Channel is of type __bounded_channel__.]]
-[[Effects:] [Sets the upper bound of the __bounded_channel__.]]
-[[Postconditions:] [`this->upper_bound() == hwm`.]]
-[[Throws:] [`boost::tp::invalid_watermark`]]
-[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:get_lower_bound Member function `lower_bound()`]
-
- std::size_t lower_bound();
-
-[variablelist
-[[Preconditions:] [Channel is of type __bounded_channel__.]]
-[[Effects:] [Returns the lower bound of the __bounded_channel__.]]
-[[Throws:] [Nothing]]
-[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:set_lower_bound Member function `lower_bound( low_watermark const& lwm)`]
-
- void lower_bound( low_watermark const& lwm);
-
-[variablelist
-[[Preconditions:] [Channel is of type __bounded_channel__.]]
-[[Effects:] [Sets the lower bound of the __bounded_channel__.]]
-[[Postconditions:] [`this->lower_bound() == lwm`.]]
-[[Throws:] [`boost::tp::invalid_watermark`]]
-[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
-]
-[endsect]
-
-
-[section:submit Member function `submit( Act const& act)`]
-
- template< typename Act >
- task< typename result_of< Act() >::type > submit( Act const& act);
-
-[variablelist
-[[Preconditions:] [has_priority< pool >::value == false && ! closed()]]
-[[Effects:] [Submits an __action__ to the pool and returns a __task__ object.]]
-[[Throws:] [`boost::tp::task_rejected`]]
-]
-[endsect]
-
-
-[section:submit_attr Member function `submit( Act const& act, Attr const& attr)`]
-
- template< typename Act, typename Attr >
- task< typename result_of< Act() >::type > submit( Act const& act, Attr const& attr);
-
-[variablelist
-[[Preconditions:] [has_priority< pool >::value == true && ! closed()]]
-[[Effects:] [Submits an __action__ to the pool and returns a __task__ object. __Action__ is scheduled by the attribute.]]
-[[Throws:] [`boost::tp::task_rejected`]]
-]
-[endsect]
-
-
-[section:get_default_pool Non-member function `get_default_pool()`]
-
- pool< unbounded_channel< fifo > > & get_default_pool();
-
-[variablelist
-[[Effects:] [Get access to default thread pool (static).]]
-]
-[endsect]
-
-
-[section:launch_in_pool Non-member function `launch_in_pool( Act const& act)`]
-
- template< typename Act >
- task< R > launch_in_pool( Act const& act);
-
-[variablelist
-[[Preconditions:] [has_priority< pool >::value == false && ! closed()]]
-[[Effects:] [Submits an __action__ to the default pool and returns a __task__ object.]]
-[[Throws:] [`boost::tp::task_rejected`]]
-]
-[endsect]
-
-
-[endsect]
Deleted: sandbox/task/libs/task/doc/poolsize_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/poolsize_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,43 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:poolsize Class `poolsize`]
-
- #include <boost/tp/poolsize.hpp>
-
- class poolsize
- {
- public:
- explicit poolsize( std::size_t value);
-
- operator std::size_t () const;
- };
-
-[section:constructor Constructor]
-
- explicit poolsize( std::size_t value);
-
-[variablelist
-[[Preconditions:][value > 0]]
-[[Effects:] [Constructs a `boost::tp::poolsize` instance.]]
-[[Postconditions:][operator std::size_t () > 0]]
-[[Throws:] [`boost::tp::invalid_poolsize`]]
-]
-[endsect]
-
-
-[section:operator Member function `operator std::size_t()`]
-
- operator std::size_t () const;
-
-[variablelist
-[[Effects:] [Returns pool size.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
Added: sandbox/task/libs/task/doc/ref_exceptions.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_exceptions.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,126 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:invalid_poolsize Class `invalid_poolsize`]
+
+ #include <boost/tp/exceptions.hpp>
+
+ class invalid_poolsize
+ : public std::invalid_argument
+ {
+ public:
+ invalid_poolsize( std::string const& msg);
+ };
+
+[section:constructor Constructor]
+
+ invalid_poolsize( std::string const& msg);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::invalid_poolsize` instance.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
+
+[section:invalid_scanns Class `invalid_scanns`]
+
+ #include <boost/tp/exceptions.hpp>
+
+ class invalid_scanns
+ : public std::invalid_argument
+ {
+ public:
+ invalid_scanns( std::string const& msg);
+ };
+
+[section:constructor Constructor]
+
+ invalid_scanns( std::string const& msg);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::invalid_scanns` instance.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
+
+[section:invalid_timeduration Class `invalid_timeduration`]
+
+ #include <boost/tp/exceptions.hpp>
+
+ class invalid_timeduration
+ : public std::invalid_argument
+ {
+ public:
+ invalid_timeduration( std::string const& msg);
+ };
+
+[section:constructor Constructor]
+
+ invalid_timeduration( std::string const& msg);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::invalid_timeduration` instance.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
+
+[section:invalid_watermark Class `invalid_watermark`]
+
+ #include <boost/tp/exceptions.hpp>
+
+ class invalid_watermark
+ : public std::invalid_argument
+ {
+ public:
+ invalid_watermark( std::string const& msg);
+ };
+
+[section:constructor Constructor]
+
+ invalid_watermark( std::string const& msg);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::invalid_watermark` instance.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
+
+[section:task_rejected Class `task_rejected`]
+
+ #include <boost/tp/exceptions.hpp>
+
+ class task_rejected
+ : public std::runtime_error
+ {
+ public:
+ task_rejected( std::string const& msg);
+ };
+
+[section:constructor Constructor]
+
+ task_rejected( std::string const& msg);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::task_rejected` instance.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
Added: sandbox/task/libs/task/doc/ref_meta.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_meta.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,36 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:has_priority Meta function `has_priority`]
+
+ #include <boost/tp/info.hpp>
+
+ template< typename Pool >
+ struct has_priority
+ :
+ public mpl::bool_<
+ is_same<
+ detail::has_priority,
+ typename Pool::scheduler_type::priority_tag_type
+ >::value
+ >
+ {};
+
+[endsect]
+
+
+[section:priority_type Meta function `priority_type`]
+
+ #include <boost/tp/info.hpp>
+
+ template< typename Pool >
+ struct priority_type
+ {
+ typedef typename Pool::scheduler_type::attribute_type type;
+ };
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_poolsize.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_poolsize.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,43 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:poolsize Class `poolsize`]
+
+ #include <boost/tp/poolsize.hpp>
+
+ class poolsize
+ {
+ public:
+ explicit poolsize( std::size_t value);
+
+ operator std::size_t () const;
+ };
+
+[section:constructor Constructor]
+
+ explicit poolsize( std::size_t value);
+
+[variablelist
+[[Preconditions:][value > 0]]
+[[Effects:] [Constructs a `boost::tp::poolsize` instance.]]
+[[Postconditions:][operator std::size_t () > 0]]
+[[Throws:] [`boost::tp::invalid_poolsize`]]
+]
+[endsect]
+
+
+[section:operator Member function `operator std::size_t()`]
+
+ operator std::size_t () const;
+
+[variablelist
+[[Effects:] [Returns pool size.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_stacksize.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_stacksize.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,42 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:stacksize Class `stacksize`]
+
+ #include <boost/tp/stacksize.hpp>
+
+ class stacksize
+ {
+ public:
+ explicit stacksize( std::size_t value);
+
+ operator std::size_t () const;
+ };
+
+[section:constructor Constructor]
+
+ explicit stacksize( std::size_t value);
+
+[variablelist
+[[Preconditions:][value > 0]]
+[[Effects:] [Constructs a `boost::tp::stacksize` instance.]]
+[[Postconditions:][operator std::size_t () > 0]]
+[[Throws:] [`boost::tp::invalid_stacksize`]]
+]
+[endsect]
+
+[section:operator Member function `operator std::size_t()`]
+
+ operator std::size_t () const;
+
+[variablelist
+[[Effects:] [Returns stack size.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_static_pool.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_static_pool.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,353 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:pool Class template `pool`]
+
+ #include <boost/tp/pool.hpp>
+
+ template< typename Channel >
+ class pool
+ : private noncopyable
+ {
+ public:
+ explicit pool(
+ poolsize const& psize,
+ posix_time::time_duration const& asleep = posix_time::microseconds( 10),
+ scanns const& scns = scanns( 20) );
+
+ explicit pool(
+ poolsize const& psize,
+ high_watermark const& hwm,
+ low_watermark const& lwm,
+ posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
+ scanns const& scns = scanns( 20) );
+
+
+ explicit pool(
+ posix_time::time_duration const& asleep = posix_time::microseconds( 10),
+ scanns const& scns = scanns( 20) );
+
+ explicit pool(
+ high_watermark const& hwm,
+ low_watermark const& lwm,
+ posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
+ scanns const& scns = scanns( 20) );
+
+ ~pool();
+
+ std::size_t size();
+ std::size_t active();
+ std::size_t idle();
+
+ void shutdown();
+ const std::vector< callable > shutdown_now();
+
+ bool closed();
+ void clear();
+ bool empty();
+ std::size_t pending();
+
+ const std::size_t upper_bound();
+ void upper_bound( high_watermark const& hwm);
+ const std::size_t lower_bound();
+ void lower_bound( low_watermark const& lwm);
+
+ template< typename Act >
+ task< typename result_of< Act() >::type > submit( Act const& act);
+
+ template< typename Act, typename Attr >
+ task< typename result_of< Act() >::type > submit(
+ Act const& act,
+ Attr const& attr);
+ };
+
+ pool< unbounded_channel< fifo > > & get_default_pool();
+
+ template< typename Act >
+ task< R > launch_in_pool( Act const& act);
+
+[section:constructor_unbounded_channel_hw Constructor (unbounded channel)]
+
+ explicit pool(
+ posix_time::time_duration const& asleep = posix_time::microseconds( 10),
+ scanns const& scns = scanns( 20) );
+
+[variablelist
+[[Preconditions:] [Operating system provides functionality for processor pining.]]
+[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. For each processor a worker-thread is created and each worker-thread is pined exactly to one processor.]]
+[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`]]
+[[Notes:] [Constructor has to be called if a __unbounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:constructor_unbounded_channel Constructor (unbounded channel)]
+
+ explicit pool(
+ poolsize const& psize,
+ posix_time::time_duration const& asleep = posix_time::microseconds( 10),
+ scanns const& scns = scanns( 20) );
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. Pool contains psize worker-threads.]]
+[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`]]
+[[Notes:] [Constructor has to be called if a __unbounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:constructor_bounded_channel_hw Constructor (bounded channel)]
+
+ explicit pool(
+ high_watermark const& hwm,
+ low_watermark const& lwm,
+ posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
+ scanns const& scns = scanns( 20) );
+
+[variablelist
+[[Preconditions:] [Operating system provides functionality for processor pining.]]
+[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. For each processor a worker-thread is created and each worker-thread is pined exactly to one processor.]]
+[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`, `boost::tp::invalid_watermark`]]
+[[Notes:] [Constructor has to be called if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:constructor_bounded_channel Constructor (bounded channel)]
+
+ explicit pool(
+ poolsize const& psize,
+ high_watermark const& hwm,
+ low_watermark const& lwm,
+ posix_time::time_duration const& asleep = posix_time::milliseconds( 100),
+ scanns const& scns = scanns( 20) );
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::pool< Channel >` instance. Pool contains psize worker-threads.]]
+[[Throws:] [`boost::tp::invalid_scanns`, `boost::tp::invalid_timeduration`, `boost::tp::invalid_watermark`]]
+[[Notes:] [Constructor has to be called if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:destructor Destructor]
+
+ ~pool();
+
+[variablelist
+[[Effects:] [Calls `boost::tp::pool< Channel >::shutdown()` if not yet called.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:size Member function `size()`]
+
+ std::size_t size();
+
+[variablelist
+[[Effects:] [Returns how many worker threads are running in the pool.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:active Member function `active()`]
+
+ std::size_t active();
+
+[variablelist
+[[Effects:] [Returns how many worker threads are active (executing an __action__).]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:idle Member function `idle()`]
+
+ std::size_t idle();
+
+[variablelist
+[[Effects:] [Returns how many worker threads are idle (not executing an __action__).]]
+[[Throws:] [Nothing]]
+[[Notes:] [The value is the difference of `size()` and `active()`]]
+]
+[endsect]
+
+
+[section:shutdown Member function `shutdown()`]
+
+ void shutdown();
+
+[variablelist
+[[Effects:] [Deactivates the channel and joins all worker threads. The pool is closed.]]
+[[Throws:] [Nothing]]
+[[Notes:] [All pending __actions__ are processed.]]
+]
+[endsect]
+
+
+[section:shutdown_now Member function `shutdown_now()`]
+
+ const std::vector< callable > shutdown_now();
+
+[variablelist
+[[Effects:] [Deactivates the channel, send interruption request to all worker threads and joins them. The pool is closed.]]
+[[Throws:] [Nothing]]
+[[Notes:] [Pending __actions__ are not processed but returned.]]
+]
+[endsect]
+
+
+[section:losed Member function `closed()`]
+
+ bool closed();
+
+[variablelist
+[[Effects:] [Queries if the pool is closed (pool is shutdown).]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:clear Member function `clear()`]
+
+ void clear();
+
+[variablelist
+[[Effects:] [Removes all pending __actions__ from the __channel__.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:empty Member function `empty()`]
+
+ bool empty();
+
+[variablelist
+[[Effects:] [Queries if the __channel__ is empty.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:pending Member function `pending()`]
+
+ std::size_t pending();
+
+[variablelist
+[[Effects:] [Queries how many __actions__ are pending in the __channel__.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:get_upper_bound Member function `upper_bound()`]
+
+ std::size_t upper_bound();
+
+[variablelist
+[[Preconditions:] [Channel is of type __bounded_channel__.]]
+[[Effects:] [Returns the upper bound of the __bounded_channel__.]]
+[[Throws:] [Nothing]]
+[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:set_upper_bound Member function `upper_bound( high_watermark const& hwm)`]
+
+ void upper_bound( high_watermark const& hwm);
+
+[variablelist
+[[Preconditions:] [Channel is of type __bounded_channel__.]]
+[[Effects:] [Sets the upper bound of the __bounded_channel__.]]
+[[Postconditions:] [`this->upper_bound() == hwm`.]]
+[[Throws:] [`boost::tp::invalid_watermark`]]
+[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:get_lower_bound Member function `lower_bound()`]
+
+ std::size_t lower_bound();
+
+[variablelist
+[[Preconditions:] [Channel is of type __bounded_channel__.]]
+[[Effects:] [Returns the lower bound of the __bounded_channel__.]]
+[[Throws:] [Nothing]]
+[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:set_lower_bound Member function `lower_bound( low_watermark const& lwm)`]
+
+ void lower_bound( low_watermark const& lwm);
+
+[variablelist
+[[Preconditions:] [Channel is of type __bounded_channel__.]]
+[[Effects:] [Sets the lower bound of the __bounded_channel__.]]
+[[Postconditions:] [`this->lower_bound() == lwm`.]]
+[[Throws:] [`boost::tp::invalid_watermark`]]
+[[Notes:] [Can only be used if a __bounded_channel__ is used.]]
+]
+[endsect]
+
+
+[section:submit Member function `submit( Act const& act)`]
+
+ template< typename Act >
+ task< typename result_of< Act() >::type > submit( Act const& act);
+
+[variablelist
+[[Preconditions:] [has_priority< pool >::value == false && ! closed()]]
+[[Effects:] [Submits an __action__ to the pool and returns a __task__ object.]]
+[[Throws:] [`boost::tp::task_rejected`]]
+]
+[endsect]
+
+
+[section:submit_attr Member function `submit( Act const& act, Attr const& attr)`]
+
+ template< typename Act, typename Attr >
+ task< typename result_of< Act() >::type > submit( Act const& act, Attr const& attr);
+
+[variablelist
+[[Preconditions:] [has_priority< pool >::value == true && ! closed()]]
+[[Effects:] [Submits an __action__ to the pool and returns a __task__ object. __Action__ is scheduled by the attribute.]]
+[[Throws:] [`boost::tp::task_rejected`]]
+]
+[endsect]
+
+
+[section:get_default_pool Non-member function `get_default_pool()`]
+
+ pool< unbounded_channel< fifo > > & get_default_pool();
+
+[variablelist
+[[Effects:] [Get access to default thread pool (static).]]
+]
+[endsect]
+
+
+[section:launch_in_pool Non-member function `launch_in_pool( Act const& act)`]
+
+ template< typename Act >
+ task< R > launch_in_pool( Act const& act);
+
+[variablelist
+[[Preconditions:] [has_priority< pool >::value == false && ! closed()]]
+[[Effects:] [Submits an __action__ to the default pool and returns a __task__ object.]]
+[[Throws:] [`boost::tp::task_rejected`]]
+]
+[endsect]
+
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_task.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_task.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,162 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:task Class template `task`]
+
+ #include <boost/tp/task.hpp>
+
+ template< typename R >
+ class task
+ {
+ public:
+ template< typename Pool >
+ task(
+ Pool * pool,
+ future< R > const& fut,
+ detail::interrupter const& intr);
+
+ void interrupt();
+ void interrupt_and_wait();
+ void interrupt_and_wait( system_time const& abs_time);
+ template< typename Duration >
+ void interrupt_and_wait( Duration const& rel_time);
+ bool interrupt_requested();
+
+ R get() const;
+
+ bool is_ready() const;
+ bool has_value() const;
+ bool has_exception() const;
+
+ void wait() const;
+ template< typename Duration >
+ bool timed_wait( Duration const& rel_time) const;
+ bool timed_wait_until( system_time const& abs_time) const;
+ };
+
+[section:constructor Constructor]
+
+ template< typename Pool >
+ task(
+ Pool * pool,
+ future< R > const& fut,
+ detail::interrupter const& intr);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::task< R >` instance.]]
+[[Throws:] [Nothing]]
+[[Notes:] [task objects should only be constructed by the pool.]]
+]
+[endsect]
+
+
+[section:interrupt Member function `interrupt()`]
+
+ void interrupt();
+
+[variablelist
+[[Effects:] [Associated __action__ will be interrupted the next time it enters a __interruption_point__ if interruption is not disabled. The function returns immediatly.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:interrupt_and_wait Member function `interrupt_and_wait()`]
+
+ void interrupt_and_wait();
+
+ void interrupt_and_wait( system_time const& abs_time);
+
+ template< typename DurationTime >
+ void interrupt_and_wait( DurationTime const& rel_time);
+
+[variablelist
+[[Effects:] [Associated __action__ will be interrupted the next time it enters one __interruption_point__ if interruption is not disabled. The function waits until the __action__ has terminated or the specified duration td has elapsed.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:get Member function `get()`]
+
+ R get() const;
+
+[variablelist
+[[Effects:] [Returns fulfilled value or throws fulfilled exception.]]
+[[Throws:] [`boost::future::broken_promise`]]
+]
+[endsect]
+
+
+[section:is_read Member function `is_ready()`]
+
+ bool is_ready() const;
+
+[variablelist
+[[Effects:] [Queries if the __action__ has been fulfilled.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:has_value Member function `has_value()`]
+
+ bool has_value() const;
+
+[variablelist
+[[Effects:] [Queries if the __action__ has been fulfilled (is ready) and has a value.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:has_exception Member function `has_exception()`]
+
+ bool has_exception() const;
+
+[variablelist
+[[Effects:] [Queries if the __action__ has been fulfilled (is ready) and has an exception.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+
+[section:wait Member function `wait()`]
+
+ void wait() const;
+
+[variablelist
+[[Effects:] [Waits until the result is ready.]]
+[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
+]
+[endsect]
+
+
+[section:timed_wait Member function `timed_wait()`]
+
+ template< typename Duration >
+ bool timed_wait( Duration const& wait_duration);
+
+[variablelist
+[[Effects:] [Waits until the result is ready, or returns false if the time specified by wait_duration has elapsed.]]
+[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
+]
+[endsect]
+
+
+[section:timed_wait_until Member function `timed_wait_until()`]
+
+ bool timed_wait_until( system_time const& wait_timeout);
+
+[variablelist
+[[Effects:] [Waits until the result is ready, or returns false if the time point specified by wait_timeout has passed.]]
+[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
+]
+[endsect]
+
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_this_task.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_this_task.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,64 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:reschedule_until Non-member function `reschedule_until()`]
+
+ #include <boost/tp/pool.hpp>
+
+ template< typename Pred >
+ void reschedule_until( Pred const&);
+
+[variablelist
+[[Effects:] [Reschedules current task until passed callable predicate becomes ready.]
+[[Throws:] [Nothing.]]
+[[Note:] [This function resides in namespace `boost::this_task`.]]
+]
+
+[endsect]
+
+[section:get_thread_pool Non-member function `get_thread_pool()`]
+
+ #include <boost/tp/pool.hpp>
+
+ template< typename Pool >
+ Pool & get_thread_pool();
+
+[variablelist
+[[Effects:] [Returns reference to the thread pool where the current worker thread is running.]
+[[Throws:] [Nothing.]]
+[[Note:] [This function resides in namespace `boost::this_task`.]]
+]
+
+[endsect]
+
+[section:is_worker Non-member function `is_worker()`]
+
+ #include <boost/tp/pool.hpp>
+
+ bool is_worker();
+
+[variablelist
+[[Effects:] [Returns true if the current thread is a worker-thread form a pool.]
+[[Throws:] [Nothing.]]
+[[Note:] [This function resides in namespace `boost::this_task`.]]
+]
+
+[endsect]
+
+[section:worker_id Non-member function `worker_id()`]
+
+ #include <boost/tp/pool.hpp>
+
+ thread::id worker_id();
+
+[variablelist
+[[Effects:] [Returns returns the thread-id of the worker-thread.]
+[[Throws:] [Nothing.]]
+[[Note:] [This function resides in namespace `boost::this_task`.]]
+]
+
+[endsect]
Added: sandbox/task/libs/task/doc/ref_watermark.qbk
==============================================================================
--- (empty file)
+++ sandbox/task/libs/task/doc/ref_watermark.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -0,0 +1,75 @@
+[/
+ (C) Copyright 2008 Oliver Kowalke.
+ 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:high_watermark Class `high_watermark`]
+
+ #include <boost/tp/watermark.hpp>
+
+ class high_watermark
+ {
+ public:
+ explicit high_watermark( std::size_t value);
+
+ operator std::size_t () const;
+ };
+
+[section:constructor Constructor]
+
+ explicit high_watermark( std::size_t value);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::high_watermark` instance.]]
+[[Throws:] [`boost::tp::invalid_watermark`]]
+]
+[endsect]
+
+[section:operator Member function `operator std::size_t()`]
+
+ operator std::size_t () const;
+
+[variablelist
+[[Effects:] [Returns high watermark.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
+
+
+[section:low_watermark Class `low_watermark`]
+
+ #include <boost/tp/watermark.hpp>
+
+ class low_watermark
+ {
+ public:
+ explicit low_watermark( std::size_t value);
+
+ operator std::size_t () const;
+ };
+
+[section:constructor Constructor]
+
+ explicit low_watermark( std::size_t value);
+
+[variablelist
+[[Effects:] [Constructs a `boost::tp::low_watermark` instance.]]
+[[Throws:] [`boost::tp::invalid_watermark`]]
+]
+[endsect]
+
+[section:operator Member function `operator std::size_t()`]
+
+ operator std::size_t () const;
+
+[variablelist
+[[Effects:] [Returns low watermark.]]
+[[Throws:] [Nothing]]
+]
+[endsect]
+
+[endsect]
\ No newline at end of file
Deleted: sandbox/task/libs/task/doc/scanns_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/scanns_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,42 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:scanns Class `scanns`]
-
- #include <boost/tp/scanns.hpp>
-
- class scanns
- {
- public:
- explicit scanns( std::size_t value);
-
- operator std::size_t () const;
- };
-
-[section:constructor Constructor]
-
- explicit scanns( std::size_t value);
-
-[variablelist
-[[Preconditions:][value >= 0]]
-[[Effects:] [Constructs a `boost::tp::scanns` instance.]]
-[[Postconditions:][operator std::size_t () >= 0]]
-[[Throws:] [`boost::tp::invalid_scanns`]]
-]
-[endsect]
-
-[section:operator Member function `operator std::size_t()`]
-
- operator std::size_t () const;
-
-[variablelist
-[[Effects:] [Returns scanns size.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
Deleted: sandbox/task/libs/task/doc/stacksize_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/stacksize_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,42 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:stacksize Class `stacksize`]
-
- #include <boost/tp/stacksize.hpp>
-
- class stacksize
- {
- public:
- explicit stacksize( std::size_t value);
-
- operator std::size_t () const;
- };
-
-[section:constructor Constructor]
-
- explicit stacksize( std::size_t value);
-
-[variablelist
-[[Preconditions:][value > 0]]
-[[Effects:] [Constructs a `boost::tp::stacksize` instance.]]
-[[Postconditions:][operator std::size_t () > 0]]
-[[Throws:] [`boost::tp::invalid_stacksize`]]
-]
-[endsect]
-
-[section:operator Member function `operator std::size_t()`]
-
- operator std::size_t () const;
-
-[variablelist
-[[Effects:] [Returns stack size.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
Modified: sandbox/task/libs/task/doc/task.qbk
==============================================================================
--- sandbox/task/libs/task/doc/task.qbk (original)
+++ sandbox/task/libs/task/doc/task.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
@@ -1,43 +1,31 @@
[/
- (C) Copyright 2008 Oliver Kowalke.
- 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).
+ 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:task Task]
-Even without parent/child relationships, Task is a major improvement over QUWI. QUWI returns nothing of use to the caller; it simply queues a delegate, and leaves it up to the implementation of that delegate to coordinate its activities with the rest of the application. QUWI provides no means of waiting for the completion of the work item, for handling exceptions, or getting the result of a computation. Task provides all of this in a very easy-to-use form, while adding very little overhead vs. QUWI.
+[section:task Task]
-The fact that Task has a Wait method is not just a convenience; it eliminates one of the most common problems people face when using QUWI. It is fairly common for one work item to need to wait for the execution of another work item to complete. If the second work item has not yet begun executing, it will be sitting in the queue waiting for a worker thread to pick it up. It is possible that there are no available worker threads – maybe they’re all waiting for other work items to complete! This can cause deadlock in the worst case, and very slow execution in the best, as the thread pool may be slow to add more worker threads to pick up these work items. Task.Wait, on the other hand, knows it’s waiting for another task, and is tightly integrated with the thread pool such that it is able to determine whether the task has started executing, and if not it executes it immediately, in-line on the current thread. This greatly improves performance and eliminates the possibility of deadlock in this situati
on.
+A task is a chunk of code that can be executed independently.
-For new code, Task is now the preferred way to queue work to the thread pool.
+__task__ represents a __callable__ object containing the unit of code to be execute by a link_ae[__ae__]. It returns a link_act[__act__] allowing to wait for the completion of the computation of the task, for getting the result of a computation or for transfering exceptions.
-Top-level Tasks have no parent. These are Tasks created by non-thread-pool threads, or with certain options specified at Task-creation time. These tasks are queued to the same FIFO queue we use for QUWI, and thus benefit from the improvements we’ve made there – but they are also subject to the same limitations. Tasks queued in this way are simply a better QUWI – but now the fun starts: A parent task can create child tasks. This happens whenever a Task creates another Task (unless it overrides this behavior). These children are implicitly treated as sub-tasks of the larger task. We assume that sub-tasks can be executed in any order – fairness is not necessary – because all that matters is that the overall operation be completed as fast as possible. This lets us throw those FIFO restrictions out the window, and opens up the possibility for much more efficient work scheduling strategies.
-Since a child task is just a piece of a larger task, we don’t need to worry about execution order. We just need to execute these things quickly. One well-known strategy for fast execution of unordered work items is “work stealing.â€
+[heading:create_task Creation]
-
-For each submitted __action__ a new task object will be created and returned by the pool.
+__fn_make_task__ can be used to create __task__.
The __task__ object acts as a proxy for a result that is initially not known and gets evaluated later by a __worker_thread__. It transports the result (value or exception) of the __action__ back to the caller.
- boost::tp::pool<
- boost::tp::unbounded_channel< boost::tp::fifo >
- > pool( boost::tp::poolsize( 10) );
-
- // task calculates fibonacci(10)
- // scheduled in unbounded channel with FIFO ordering
- boost::tp::task< int > t(
- pool.submit(
- boost::bind(
- fibonacci_fn,
- 10) ) );
+ boost::task::task< int > t1(
+ boost::task::make_task(
+ parallel_fib,
+ 10) );
- std::cout << t.get() << std::endl; // 55
+[heading:cooperative_task Interruption]
-
-[heading Interruption]
-The returned __task__ object provides the possiblity to interrupt an __action__ if it is cooperative.
+__task__ object provides the possiblity to interrupt an __action__ if it is cooperative.
An __action__ is known as cooperative if it includes interruption points in its code:
* `boost::thread::join()`
@@ -88,7 +76,9 @@
// throws boost::thread_interrupted exception
std::cout << t.get() << std::endl;
-[heading Exceptions in tasks]
+
+[heading:task_exceptions Exceptions]
+
Exceptions thrown inside an __action__ are transported by the associated task object.
Exceptions rethrown by type:
@@ -132,4 +122,11 @@
std::cout << t.get() << std::endl; // will rethrow an std::runtime_error
+[heading:parent_tasks Parent-tasks]
+
+Top-level Tasks have no parent. These are Tasks created by non-thread-pool threads, or with certain options specified at Task-creation time. These tasks are queued to the same FIFO queue we use for QUWI, and thus benefit from the improvements we’ve made there – but they are also subject to the same limitations. Tasks queued in this way are simply a better QUWI – but now the fun starts: A parent task can create child tasks. This happens whenever a Task creates another Task (unless it overrides this behavior). These children are implicitly treated as sub-tasks of the larger task. We assume that sub-tasks can be executed in any order – fairness is not necessary – because all that matters is that the overall operation be completed as fast as possible. This lets us throw those FIFO restrictions out the window, and opens up the possibility for much more efficient work scheduling strategies.
+
+Since a child task is just a piece of a larger task, we don’t need to worry about execution order. We just need to execute these things quickly. One well-known strategy for fast execution of unordered work items is link_work_stealing[__work_stealing__].
+
+
[endsect]
Deleted: sandbox/task/libs/task/doc/task_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/task_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,162 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:task Class template `task`]
-
- #include <boost/tp/task.hpp>
-
- template< typename R >
- class task
- {
- public:
- template< typename Pool >
- task(
- Pool * pool,
- future< R > const& fut,
- detail::interrupter const& intr);
-
- void interrupt();
- void interrupt_and_wait();
- void interrupt_and_wait( system_time const& abs_time);
- template< typename Duration >
- void interrupt_and_wait( Duration const& rel_time);
- bool interrupt_requested();
-
- R get() const;
-
- bool is_ready() const;
- bool has_value() const;
- bool has_exception() const;
-
- void wait() const;
- template< typename Duration >
- bool timed_wait( Duration const& rel_time) const;
- bool timed_wait_until( system_time const& abs_time) const;
- };
-
-[section:constructor Constructor]
-
- template< typename Pool >
- task(
- Pool * pool,
- future< R > const& fut,
- detail::interrupter const& intr);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::task< R >` instance.]]
-[[Throws:] [Nothing]]
-[[Notes:] [task objects should only be constructed by the pool.]]
-]
-[endsect]
-
-
-[section:interrupt Member function `interrupt()`]
-
- void interrupt();
-
-[variablelist
-[[Effects:] [Associated __action__ will be interrupted the next time it enters a __interruption_point__ if interruption is not disabled. The function returns immediatly.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:interrupt_and_wait Member function `interrupt_and_wait()`]
-
- void interrupt_and_wait();
-
- void interrupt_and_wait( system_time const& abs_time);
-
- template< typename DurationTime >
- void interrupt_and_wait( DurationTime const& rel_time);
-
-[variablelist
-[[Effects:] [Associated __action__ will be interrupted the next time it enters one __interruption_point__ if interruption is not disabled. The function waits until the __action__ has terminated or the specified duration td has elapsed.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:get Member function `get()`]
-
- R get() const;
-
-[variablelist
-[[Effects:] [Returns fulfilled value or throws fulfilled exception.]]
-[[Throws:] [`boost::future::broken_promise`]]
-]
-[endsect]
-
-
-[section:is_read Member function `is_ready()`]
-
- bool is_ready() const;
-
-[variablelist
-[[Effects:] [Queries if the __action__ has been fulfilled.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:has_value Member function `has_value()`]
-
- bool has_value() const;
-
-[variablelist
-[[Effects:] [Queries if the __action__ has been fulfilled (is ready) and has a value.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:has_exception Member function `has_exception()`]
-
- bool has_exception() const;
-
-[variablelist
-[[Effects:] [Queries if the __action__ has been fulfilled (is ready) and has an exception.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-
-[section:wait Member function `wait()`]
-
- void wait() const;
-
-[variablelist
-[[Effects:] [Waits until the result is ready.]]
-[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
-]
-[endsect]
-
-
-[section:timed_wait Member function `timed_wait()`]
-
- template< typename Duration >
- bool timed_wait( Duration const& wait_duration);
-
-[variablelist
-[[Effects:] [Waits until the result is ready, or returns false if the time specified by wait_duration has elapsed.]]
-[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
-]
-[endsect]
-
-
-[section:timed_wait_until Member function `timed_wait_until()`]
-
- bool timed_wait_until( system_time const& wait_timeout);
-
-[variablelist
-[[Effects:] [Waits until the result is ready, or returns false if the time point specified by wait_timeout has passed.]]
-[[Throws:] [Throws thread_interrupted if the result is not ready at the point of the call, and the current thread is interrupted.]]
-]
-[endsect]
-
-
-[endsect]
Deleted: sandbox/task/libs/task/doc/this_task_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/this_task_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,64 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:reschedule_until Non-member function `reschedule_until()`]
-
- #include <boost/tp/pool.hpp>
-
- template< typename Pred >
- void reschedule_until( Pred const&);
-
-[variablelist
-[[Effects:] [Reschedules current task until passed callable predicate becomes ready.]
-[[Throws:] [Nothing.]]
-[[Note:] [This function resides in namespace `boost::this_task`.]]
-]
-
-[endsect]
-
-[section:get_thread_pool Non-member function `get_thread_pool()`]
-
- #include <boost/tp/pool.hpp>
-
- template< typename Pool >
- Pool & get_thread_pool();
-
-[variablelist
-[[Effects:] [Returns reference to the thread pool where the current worker thread is running.]
-[[Throws:] [Nothing.]]
-[[Note:] [This function resides in namespace `boost::this_task`.]]
-]
-
-[endsect]
-
-[section:is_worker Non-member function `is_worker()`]
-
- #include <boost/tp/pool.hpp>
-
- bool is_worker();
-
-[variablelist
-[[Effects:] [Returns true if the current thread is a worker-thread form a pool.]
-[[Throws:] [Nothing.]]
-[[Note:] [This function resides in namespace `boost::this_task`.]]
-]
-
-[endsect]
-
-[section:worker_id Non-member function `worker_id()`]
-
- #include <boost/tp/pool.hpp>
-
- thread::id worker_id();
-
-[variablelist
-[[Effects:] [Returns returns the thread-id of the worker-thread.]
-[[Throws:] [Nothing.]]
-[[Note:] [This function resides in namespace `boost::this_task`.]]
-]
-
-[endsect]
Deleted: sandbox/task/libs/task/doc/watermark_ref.qbk
==============================================================================
--- sandbox/task/libs/task/doc/watermark_ref.qbk 2009-05-15 17:31:26 EDT (Fri, 15 May 2009)
+++ (empty file)
@@ -1,75 +0,0 @@
-[/
- (C) Copyright 2008 Oliver Kowalke.
- 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:high_watermark Class `high_watermark`]
-
- #include <boost/tp/watermark.hpp>
-
- class high_watermark
- {
- public:
- explicit high_watermark( std::size_t value);
-
- operator std::size_t () const;
- };
-
-[section:constructor Constructor]
-
- explicit high_watermark( std::size_t value);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::high_watermark` instance.]]
-[[Throws:] [`boost::tp::invalid_watermark`]]
-]
-[endsect]
-
-[section:operator Member function `operator std::size_t()`]
-
- operator std::size_t () const;
-
-[variablelist
-[[Effects:] [Returns high watermark.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
-
-
-[section:low_watermark Class `low_watermark`]
-
- #include <boost/tp/watermark.hpp>
-
- class low_watermark
- {
- public:
- explicit low_watermark( std::size_t value);
-
- operator std::size_t () const;
- };
-
-[section:constructor Constructor]
-
- explicit low_watermark( std::size_t value);
-
-[variablelist
-[[Effects:] [Constructs a `boost::tp::low_watermark` instance.]]
-[[Throws:] [`boost::tp::invalid_watermark`]]
-]
-[endsect]
-
-[section:operator Member function `operator std::size_t()`]
-
- operator std::size_t () const;
-
-[variablelist
-[[Effects:] [Returns low watermark.]]
-[[Throws:] [Nothing]]
-]
-[endsect]
-
-[endsect]
\ No newline at end of file
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