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

Subject: [Boost-commit] svn:boost r53098 - sandbox/task/libs/task/doc
From: oliver.kowalke_at_[hidden]
Date: 2009-05-18 16:04:36

Author: olli
Date: 2009-05-18 16:04:35 EDT (Mon, 18 May 2009)
New Revision: 53098
URL: http://svn.boost.org/trac/boost/changeset/53098

Log:
* documentation

Text files modified: 
   sandbox/task/libs/task/doc/async_executor.qbk |    11 +++                                     
   sandbox/task/libs/task/doc/boost_task.qbk     |     1                                         
   sandbox/task/libs/task/doc/handle.qbk         |   119 +++++++++++++++++++++++++++++++++++---- 
   sandbox/task/libs/task/doc/todo.qbk           |    20 +++---                                  
   4 files changed, 128 insertions(+), 23 deletions(-)

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-18 16:04:35 EDT (Mon, 18 May 2009)
@@ -8,6 +8,17 @@
 
 [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.
+
+
 [include own_thread.qbk]
 [include new_thread.qbk]
 [include pool.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-18 16:04:35 EDT (Mon, 18 May 2009)
@@ -41,6 +41,7 @@
 [def __as_sub_task__ `boost::task::as_sub_task`]
 [def __bounded_channel__ `boost::task::bounded_channel`]
 [def __default_pool__ `boost::task::default_pool`]
+[def __dynamic_pool__ `boost::task::dynamic_pool`]
 [def __handle__ `boost::task::handle`]
 [def __new_thread__ `boost::task::new_thread`]
 [def __own_thread__ `boost::task::own_thread`]

Modified: sandbox/task/libs/task/doc/handle.qbk
==============================================================================
--- sandbox/task/libs/task/doc/handle.qbk	(original)
+++ sandbox/task/libs/task/doc/handle.qbk	2009-05-18 16:04:35 EDT (Mon, 18 May 2009)
@@ -8,26 +8,119 @@
 
 [section:handle Handle] 
 
-__handle__ represents a __act__. It is associated by a __task__ (uniquely identified) and is returned by __fn_async__.
+__handle__ represents an __act__. It will be returned by __fn_async__ and is associated with the submitted __task__.
+
 
 [heading:act_interface Asynchronous completion token interface]
 
 __handle__ implements an interface in order to check the state of computation and result transfer
 
-* __fn_get_id__:
-* __fn_is_ready__:
-* __fn_has_value__:
-* __fn_has_exception__:
-* __fn_get__:
-* __fn_wait__:
-* __fn_wait_for__:
-* __fn_wait_until__:
+* __fn_get_id__: return id of the associated task-id
+
+* __fn_is_ready__: test if result is set
+
+* __fn_has_value__: test if value-result is set
+
+* __fn_has_exception__: test if exception-result is set
+
+* __fn_get__: return value-result
+
+* __fn_wait__: wait until result is set
+
+* __fn_wait_for__: wait until result is set or time-duration has elapsed
+
+* __fn_wait_until__: wait until result ist set or time-point has elapsed
+
+
+	long fibonacci( long n)
+	{
+		boost::this_thread::interruption_point(); // interruption point
+		
+		if ( n == 0) return 0;
+		if ( n == 1) return 1;
+		long k1( 1), k2( 0);
+		for ( int i( 2); i <= n; ++i)
+		{
+			if ( boost::this_thread::interruption_requested() )	// check if interruption was requested
+				return;
+
+			long tmp( k1);
+			k1 = k1 + k2;
+			k2 = tmp;
+		}
+		
+		boost::this_thread::interruption_point();  // interruption point
+		
+		return k1;
+	}
+
+	void main()
+	{
+		boost::task::handle< long > h(
+			boost::task::async(
+				boost::task::new_thread(),
+				boost::task::make_task(
+					fibonacci,
+					10) ) );
+		std::cout << "id == " << h.get_id() << "\n";
+		std::cout << "is ready == " << std::boolalpha << h.is_ready() << "\n";
+		h.wait();
+		std::cout << "has value == " << std::boolalpha << h.has_value() << "\n";
+		std::cout << "has exception == " << std::boolalpha << h.has_exception() << "\n";
+		std::cout << "fibonacci(10) == " << h.get() << std::endl;
+	}
+
 
 [heading:task_interruption Task interruption]
 
-* __fn_interrupt__:
-* __fn_interupt_and_wait_for__:
-* __fn_interrupt_and_wait_until__:
-* __fn_interruption_requested__:
+* __fn_interrupt__: interrupt __task__ and return immediately
+
+* __fn_interrupt_and_wait__: interrupt and wait until __task__ was removed from __worker_thread__
+
+* __fn_interrupt_and_wait_for__: interrupt and wait until __task__ was removed from __worker_thread__ or time duration has elapsed
+
+* __fn_interrupt_and_wait_until__: interrupt and wait until __task__ was removed from __worker_thread__ or time point has elapsed
+
+* __fn_interruption_requested__: return bool if interruption was requested
+
+
+	long cooperative( long n)
+	{
+		boost::this_thread::interruption_point(); // interruption point
+		
+		if ( n == 0) return 0;
+		if ( n == 1) return 1;
+		long k1( 1), k2( 0);
+		for ( int i( 2); i <= n; ++i)
+		{
+			if ( boost::this_thread::interruption_requested() )	// check if interruption was requested
+				return;
+				
+			long tmp( k1);
+			k1 = k1 + k2;
+			k2 = tmp;
+		}
+		
+		boost::this_thread::interruption_point();  // interruption point
+		
+		return k1;
+	}
+
+	void main()
+	{
+		boost::task::handle< long > 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
+					cooperative,
+					10) ) );
+		h.interrupt_and_wait();
+		std::cout << "id == " << h.get_id() << "\n";
+		std::cout << "is ready == " << std::boolalpha << h.is_ready() << "\n";
+		std::cout << "has value == " << std::boolalpha << h.has_value() << "\n";
+		std::cout << "has exception == " << std::boolalpha << h.has_exception() << "\n";
+		std::cout << h.get() << std::endl;		// throws boost::task::task_interrupted
+	}
+
 
 [endsect]

Modified: sandbox/task/libs/task/doc/todo.qbk
==============================================================================
--- sandbox/task/libs/task/doc/todo.qbk	(original)
+++ sandbox/task/libs/task/doc/todo.qbk	2009-05-18 16:04:35 EDT (Mon, 18 May 2009)
@@ -8,8 +8,12 @@
 
 [section:todo Appendix C: Future development]
 
+[heading Dynamic thread-pool]
 
-[heading Concurrency and communication mechanisms]
+* __dynamic_pool__ adds or removes __worker_threads__ from the __thread_pool__ depending on the work-load (undersubscription/oversubscription).
+
+
+[heading Communication and synchronisation abstractions]
 
 * Event variable: A event variable is a bivalued variable (up/down) on which a task can wait for an event to be set or reset. The calling task will be suspended until the state of the event variable is that required by the caller.
 
@@ -25,24 +29,20 @@
 
 * Task groups: A task group defines a graph of interdependent tasks that can mostly be run in parallel. The tasks in the group have dependencies or communicate with each other.
 
+
 [heading Support of explicit processor bindig]
-__aes__ related to a __thread_pool__ (like __default__threadpool__) could support explicit processor binding.
 
-The framework supports the possibility of an __ae__ executing the submitted task in an new spawned process or a pool of processes.
-__handle__ is still capable to manage the task inside the spawned process (works as a __act__ too).
+* __aes__ related to a __thread_pool__ (like __default__pool__) could support explicit processor binding.
+
 
 [heading Interdepended task]
 
-[heading Actor framework]
+* With special support of concurrence and synchronisation abstractions interdepended tasks work in __thread_pools__ (using context switching/fibers). 
 
-- Microsoft's terminology: is ['agents]
-- if the solution can be modeled in terms of interactive components
-- coordinate parallel (interdepended) tasks
-- 'disciplined' access to shared state that prevents common programming errors
 
 [heading Optimizations]
  
-* two-lock-queue as global queue
+* two-lock-queue as global queue in __thread_pool__
 
 * maybe lock-free-queue as global queue too (how to provide the scheduling policies fifo, priority, smart?)