|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r53145 - sandbox/task/libs/task/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-05-20 17:00:20
Author: olli
Date: 2009-05-20 17:00:19 EDT (Wed, 20 May 2009)
New Revision: 53145
URL: http://svn.boost.org/trac/boost/changeset/53145
Log:
* docu
Text files modified:
sandbox/task/libs/task/doc/as_sub_task.qbk | 43 ++++++++++++++++++++++++++++
sandbox/task/libs/task/doc/async_executor.qbk | 12 ++------
sandbox/task/libs/task/doc/boost_task.qbk | 1
sandbox/task/libs/task/doc/new_thread.qbk | 60 ++++++++++++++++++++++++++++++++++++++++
sandbox/task/libs/task/doc/overview.qbk | 4 +-
sandbox/task/libs/task/doc/own_thread.qbk | 40 ++++++++++++++++++++++++++
6 files changed, 149 insertions(+), 11 deletions(-)
Modified: sandbox/task/libs/task/doc/as_sub_task.qbk
==============================================================================
--- sandbox/task/libs/task/doc/as_sub_task.qbk (original)
+++ sandbox/task/libs/task/doc/as_sub_task.qbk 2009-05-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -1 +1,44 @@
+[/
+ 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:as_sub_task __as_sub_task__]
+
+__as_sub_task__ is a conveniet way to execute a __sub_task__. If the parent task is executed inside a __thread_pool__ the __sub_task__ is put into the local-queue of the
+__worker_thread__ in the other case the __sub_task__ will be executed in a new thread.
+
+
+``
+ boost::task::handle< long > h(
+ boost::task::async(
+ boost::task::as_sub_task(),
+ boost::task::make_task(
+ fibonacci,
+ 10) ) );
+``
+
+is equivalent to:
+
+
+``
+ if ( boost::this_task::runs_in_pool() )
+ {
+ // put the sub-task into worker-threads local-queue
+ }
+ else
+ {
+ boost::task::async(
+ boost::task::new_thread(),
+ boost::task::make_task(...) );
+ }
+``
+
+
+[endsect]
+
+
Modified: sandbox/task/libs/task/doc/async_executor.qbk
==============================================================================
--- sandbox/task/libs/task/doc/async_executor.qbk (original)
+++ sandbox/task/libs/task/doc/async_executor.qbk 2009-05-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -8,16 +8,10 @@
[section:async_executor Asynchronous executor]
-Often you will see mentioned ‘synchronous’ or ‘asynchronous’ when talking about methods. Here I explain what this means, how to use them, and what are the benefits of the two.
-Usually the methods are synchronous. That means that you call them, they gets executed. And when they finish you get the control back.
-The asynchronous methods are different. You call them. They start executing, but return the control over the execution back to the thread which called them while they continue to execute in different thread.
-
-The synchronous methods are easier to use and write and that’s why most of the methods are such. But when dealing with something which execution may last long often it is more convenient to use asynchronous functions.
-For example some internet components are asynchronous. Asynchronous is the function for shutting down Windows. This way you can close your application before the actual shutdown.
-
-Asynchronous methods have the advantage to not interrupt the program flow when a time consuming operation is needed. They are used a bit harder and have to be used carefully. You can not be sure that the execution of a method is finished, and the result is ready to use (unless you do checks).
-A good use is to call an asynchronous method, continue executing the application, and when the results of the method execution must be used, a loop like the one shown above should be made to wait for the results.
+In contrast to synchronous methods asynchronous methods do not block the program flow when a time consuming operation is executed.
+The application continues executing the current context and when the result of the asynchronous method is required the __act__ can be used.
+An __ae__ executes a __task__ asynchronously and provides a link_handle(__act__) to manage the __task__.
[include own_thread.qbk]
[include new_thread.qbk]
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-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -30,6 +30,7 @@
[template link_channel[link_text] [link boost_task.async_executor.pool.channel [link_text]]]
[template link_forkjoin[link_text] [link boost_task.async_executor.pool.forkjoin [link_text]]]
[template link_handle[link_text] [link boost_task.async_completion_token.handle [link_text]]]
+[template link_own_thread[link_text] [link boost_task.async_executor.own_thread [link_text]]]
[template link_pool[link_text] [link boost_task.async_executor.pool [link_text]]]
[template link_task[link_text] [link boost_task.task [link_text]]]
[template link_work_stealing[link_text] [link boost_task.async_executor.pool.work_stealing [link_text]]]
Modified: sandbox/task/libs/task/doc/new_thread.qbk
==============================================================================
--- sandbox/task/libs/task/doc/new_thread.qbk (original)
+++ sandbox/task/libs/task/doc/new_thread.qbk 2009-05-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -1 +1,61 @@
+[/
+ 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:new_thread __new_thread__]
+
+_new_thread__ creates a new __thread__ and executes the task in this thread (asynchronous). The created thread gets joined by handle.
+
+[caution Always store the returned __act__ in a variable because __handle__ joins the thread in its destructor (if the last reference gets out of scope). ]
+
+Points of [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2802.html N2802] should be addressed.
+
+``
+ long fibonacci( long n)
+ {
+ if ( n == 0) return 0;
+ if ( n == 1) return 1;
+ long k1( 1), k2( 0);
+ for ( int i( 2); i <= n; ++i)
+ {
+ long tmp( k1);
+ k1 = k1 + k2;
+ k2 = tmp;
+ }
+ return k1;
+ }
+
+ void main()
+ {
+ boost::task::handle< long > h(
+ boost::task::async(
+ boost::task::new_thread(),
+ boost::task::make_task(
+ fibonacci,
+ 10) ) );
+ std::cout << "fibonacci(10) == " << h.get() << std::endl;
+ }
+``
+
+
+In the example below both `a_function` and `another_function` are executed synchron (see link_own_thread[__own_thread__] for synchronous execution)!
+
+``
+ boost::task::async(
+ boost::task::new_thread(),
+ boost::task::make_task(
+ a_function) ) );
+
+ boost::task::async(
+ boost::task::new_thread(),
+ boost::task::make_task(
+ another_function) ) );
+``
+
+[endsect]
+
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-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -39,7 +39,7 @@
* N2276: Thread Pools and Futures [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2276.html] written by Anthony Williams.
-* N2802: A plea to reconsider detach-on-destruction for thread objects [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2802.html] written by Hans-J. Boehm.
+* N2802: A plea to reconsider detach-on-destruction for thread objects [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2802.html] written by Hans-J. Boehm.
* C++task-force mailing list
@@ -56,7 +56,7 @@
[heading Tested Platforms]
__boost_task__ has been tested on the following platforms and compilers:
-* Linux 2.6.29.2 (amd64), GCC 4.3.3
+* Debian GNU/Linux 2.6.29.2 (amd64), GCC 4.3.3
* FreeBSD 7.2 (amd64), GCC 4.2.1
* OpenSolaris 0811 (amd64), SUN
* Windows XP Professional (i386), MSVC 9.0
Modified: sandbox/task/libs/task/doc/own_thread.qbk
==============================================================================
--- sandbox/task/libs/task/doc/own_thread.qbk (original)
+++ sandbox/task/libs/task/doc/own_thread.qbk 2009-05-20 17:00:19 EDT (Wed, 20 May 2009)
@@ -1 +1,41 @@
+[/
+ 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:own_thread __own_thread__]
+
+__own_thread__ executes the task in the current thread (synchronous execution - concerns of [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2802.html N2802] do not aply).
+
+
+ long fibonacci( long n)
+ {
+ if ( n == 0) return 0;
+ if ( n == 1) return 1;
+ long k1( 1), k2( 0);
+ for ( int i( 2); i <= n; ++i)
+ {
+ long tmp( k1);
+ k1 = k1 + k2;
+ k2 = tmp;
+ }
+ return k1;
+ }
+
+ void main()
+ {
+ boost::task::handle< long > h(
+ boost::task::async(
+ boost::task::own_thread(),
+ boost::task::make_task(
+ fibonacci,
+ 10) ) );
+ std::cout << "fibonacci(10) == " << h.get() << std::endl;
+ }
+
+
+[endsect]
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