[Boost-commit] svn:boost r51116 - sandbox/interthreads/libs/interthreads/doc

Subject: [Boost-commit] svn:boost r51116 - sandbox/interthreads/libs/interthreads/doc
From: vicente.botet_at_[hidden]
Date: 2009-02-08 16:31:08

Author: viboes
Date: 2009-02-08 16:31:08 EST (Sun, 08 Feb 2009)
New Revision: 51116
URL: http://svn.boost.org/trac/boost/changeset/51116

Log:
interthreads version 0.4
    *  New free functions for all the AsynchronousCompletionToken  operations, providing a higher degree of freedom.
    * Missing have_all_values(), have_all_exception() and are_all_ready() functions on AsynchronousCompletionToken fusion tuples.
    * get_all: getting all the values from a tuple of AsynchronousCompletionToken works now.
    * fork_after overloaded for a single dependency
    * wait_all overloaded for a single ACT.
    * wait_for_all evaluate one of its elements on the current thread
    * No need to use wait_and_get() on thread_specific_shared_ptr<> to synchronize with the decoration if the thread is created using a AsynchronousExecutor decorator. In this case the synchro is done before returning the AsynchronousCompletionToken. See the tutorial and the mono_thread_id example.

Added:
   sandbox/interthreads/libs/interthreads/doc/models.qbk   (contents, props changed)
   sandbox/interthreads/libs/interthreads/doc/tests.qbk   (contents, props changed)
   sandbox/interthreads/libs/interthreads/doc/tickets.qbk   (contents, props changed)

Added: sandbox/interthreads/libs/interthreads/doc/models.qbk
==============================================================================
--- (empty file)
+++ sandbox/interthreads/libs/interthreads/doc/models.qbk	2009-02-08 16:31:08 EST (Sun, 08 Feb 2009)
@@ -0,0 +1,269 @@
+[/
+  (C) Copyright 2008-2009 Vicente J Botet Escriba.
+  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 Concepts]
+[/===============]
+
+[/=============================================]
+[section Asynchronous Completion Token Concepts]
+[/=============================================]
+
+[/==================]
+[section Concept `ACT` ]
+[/==================]
+
+An __ACT__ allows to to wait for the completion of an asynchronous executed operation.
+An __ACT__  should be __Movable__ or __CopyConstructible__.
+
+[variablelist Notation
+    [[`act`]        [An __ACT__]]
+    [[`f`]          [A __Nullary__ function with type F]]
+    [[`abs_time`]   [A __system_time__]]
+    [[`rel_time`]   [A __Duration__]]
+    [[`b`]          [A bool]]
+]
+
+[heading Expression requirements]
+A type models a __AE__ if, the following expressions are valid:
+
+[table
+    [[Expression]                       [Return type]   [Runtime Complexity]]
+    [[`act.wait()`]                     [void]          [Constant]]
+    [[`b = act.wait_until(abs_time)`]   [bool]          [Constant]]
+    [[`b = act.wait_for(rel_time)`]     [bool]          [Constant]]
+]
+
+[heading Meta Expressions]
+[table
+    [[Expression]                       [Type]           [Compile Time Complexity]]
+    [[`__is_movable__<ACT>::type`]      [MPL boolean]    [Constant]]
+    [[`__has_future_if__<ACT>::type`]   [MPL boolean]    [Constant]]
+    [[`__has_thread_if__<ACT>::type`]   [MPL boolean]    [Constant]]
+]
+
+[heading Expression Semantics]
+[
+table
+    [[Expression]                       [Semantics]]
+    [[`act.wait()`]                     [Waits until the `act` completes]]
+    [[`b = act.wait_until(abs_time)`]   [Waits until the `act` completes until `abs_time` is not reached]]
+    [[`b = act.wait_for(rel_time)`]     [Waits until the `act` completes for a `rel_time` duration]]
+]
+
+[heading Models]
+
+* __unique_future__
+* __shared_future__
+* __unique_joiner__
+* __shared_joiner__
+* __tp_task__
+* __thread__
+
+[endsect]
+
+[/=============================]
+[section Concept `FutureBasedACT` ]
+[/=============================]
+
+An __FutureBasedACT__ is a __ACT__ that associates a value expected on the its completion.
+
+[variablelist Notation
+    [[`act`]        [An __ACT__]]
+    [[`f`]          [A __Nullary_ function with type F]]
+    [[`abs_time`]   [A __system_time__]]
+    [[`rel_time`]   [A __Duration__]]
+    [[`b`]          [A bool]]
+    [[`v`]          [T]]
+]
+
+[heading Expression requirements]
+A type models an __FutureBasedACT__ if, in adition to being an __ACT__,
+the following expressions are valid:
+
+[table
+    [[Expression]                   [Return type]   [Runtime Complexity]]
+    [[`b = act.is_ready()`]         [bool]          [Constant]]
+    [[`b = act.has_exception()`]    [bool]          [Constant]]
+    [[`b = act.has_value()`]        [bool]          [Constant]]
+]
+
+[heading Expression Semantics]
+[table
+    [[Expression]                   [Semantics]]
+    [[`b = act.is_ready()`]         [Is true only if the associated state holds a value or an exception ready for retrieval.]]
+    [[`b = act.has_exception()`]    [true only if the associated state contains an exception.]]
+    [[`b = act.has_value()`]        [true only if the associated state contains a value]]
+    [[`v = act.get()`]              [returns the stored value]]
+]
+
+[heading Models]
+
+* __unique_future__
+* __shared_future__
+* __unique_joiner__
+* __shared_joiner__
+* __tp_task__
+
+[endsect]
+
+[/=============================]
+[section Concept `ThreadBasedACT` ]
+[/=============================]
+
+An __FutureBasedACT__ is a __ACT__ that associates a value expected on the its completion.
+
+[variablelist Notation
+    [[`act`]        [An __ACT__]]
+    [[`f`]          [A __Nullary_ function with type F]]
+    [[`abs_time`]   [A __system_time__]]
+    [[`rel_time`]   [A __Duration__]]
+    [[`b`]          [A bool]]
+    [[`id`]         [A thread::id]]
+]
+
+[heading Expression requirements]
+A type models an __FutureBasedACT__ if, in adition to being an __ACT__,
+the following expressions are valid:
+
+[table
+    [[Expression]                           [Return type]   [Runtime Complexity]]
+    [[`act.join()`]                         [void]          [Constant]]
+    [[`b = act.joinable()`]                 [bool]          [Constant]]
+    [[`b = act.join_until(abs_time)`]       [bool]          [Constant]]
+    [[`b = act.join_for(rel_time)`]         [bool]          [Constant]]
+    [[`act.detach()`]                       [void]          [Constant]]
+    [[`act.interrupt()`]                    [void]          [Constant]]
+    [[`b = act.interruption_requested()`]   [bool]          [Constant]]
+    [[`id = act.get_id()`]                  [bool]          [Constant]]
+]
+
+[heading Expression Semantics]
+[table
+    [[Expression]                           [Semantics]]
+    [[`act.join()`]                         [Constant]]
+    [[`b = act.joinable()`]                 [Constant]]
+    [[`b = act.join_until(abs_time)`]       [Constant]]
+    [[`b = act.join_for(rel_time)`]         [Constant]]
+    [[`act.detach()`]                       [Constant]]
+    [[`act.interrupt()`]                    [Constant]]
+    [[`b = act.interruption_requested()`]   [Constant]]
+    [[`is = act.get_id()`]                  [Constant]]
+]
+
+[heading Models]
+
+* __unique_joiner__
+* __shared_joiner__
+* __thread__
+* __tp_task__
+
+[endsect]
+
+[endsect]
+
+[/======================================]
+[section Asynchronous Executors Concepts]
+[/======================================]
+
+[/==========================================================================================]
+[section Concept `AsynchronousExecutor`]
+[/==========================================================================================]
+
+An __AsynchronousExecutor__ executes asynchronously a function and returns an __ACT__ when calling the fork function on it.
+
+[variablelist Notation
+    [[`ae`]             [An __AE__]]
+    [[`f`]              [A Nullary function with type F]]
+    [[`act`]            [An __ACT__]]
+]
+
+[heading Expression requirements]
+A type models a __AE__ if, the following expressions are valid:
+
+[table
+    [[Expression]               [Return type]   [Runtime Complexity]]
+    [[`__fork__(ae, f)`]        [__ACT__]       [Constant]]
+    [[`get_future<AE>()(act)`]  [__Future__]    [Constant]]
+    [[`__asynchronous_completion_token__<AE, T>::type`] [Model of __ACT__ satisfying `__act_value<ACT>::type` is `T`]             [Constant]]
+]
+
+[heading Meta Expressions]
+[table
+    [[Expression]                               [Model Of]     [Compile Time Complexity]]
+    [[`get_future<AE>::type`]                   []             [Amortized constant time]]
+    [[`__result_of_advance_c__<I, N>::type`]    []             [Linear]]
+]
+
+[heading Expression Semantics]
+[
+table
+    [[Expression]               [Semantics]]
+    [[`act = __fork__(ae, f)`]  [request `ae` to execute asynchronously the function `f`and returns an __ACT__ ]]
+    [[`get_future<AE>()(act)`]  [gets a reference to a __Future__]]
+]
+
+[heading Constraints]
+The following constraints applies:
+
+* `act_value<__ACT__>::type == boost::result_of<F()::type>`
+
+[heading Models]
+
+* __unique_threader__
+* __shared_threader__
+
+[endsect]
+
+
+[/==========================================================================================]
+[section Concept `IntrinsicAsynchronousExecutor`]
+[/==========================================================================================]
+
+
+The default fork implementation put some requirements in its __AE__ parameter. This concept is related to this.
+An __IAE__ is __AE__ that works well with the default implementation of __fork__.
+
+[variablelist Notation
+    [[`ae`]         [An __IAE__]]
+    [[`f`]          [A __Nullary__ function]]
+]
+
+[heading Expression requirements]
+A type models an __IAE__ if, in adition to being an __AE__,
+the following expressions are valid:
+
+[table
+    [[Expression]        [Return type]                           [Runtime Complexity]]
+    [[`ae.fork(f)`]      [`handle<boost::result_of<F()>::type`]  [Constant]]
+]
+
+[heading Meta Expressions]
+[table
+    [[Expression]                               [Model Of] [Compile Time Complexity]]
+    [[`handle<boost::result_of<F()>::type`]     [__ACT__]  [Constant ]]
+]
+
+[heading Expression Semantics]
+[
+table
+    [[Expression]              [Semantics]]
+    [[`ae.fork(f)`]            [executes asynchronously the function `f`and returns a __handle__ ]]
+]
+
+
+[heading Models]
+* __unique_threader__
+* __shared_threader__
+
+
+[endsect]
+
+[endsect]
+
+[endsect]

Added: sandbox/interthreads/libs/interthreads/doc/tests.qbk
==============================================================================
--- (empty file)
+++ sandbox/interthreads/libs/interthreads/doc/tests.qbk	2009-02-08 16:31:08 EST (Sun, 08 Feb 2009)
@@ -0,0 +1,56 @@
+[/
+  (C) Copyright 2008-2009 Vicente J Botet Escriba.
+  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  Appendix E: Tests]
+
+
+[section AE/ACT]
+[table
+    [[Name]                                             [Description]                                           [Pool] [BaTh][ShLa][ShTh][UnLa][UnLa] [Ticket]]
+    [[do_test_member_fork]                              [Forks and get]                                         [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_member_fork_m]                            [Forks and get]                                         [????] [Pass][Pass][????][????][????] [#]]
+    [[do_test_member_fork_bind]                         [Forks and get]                                         [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_member_fork_bind_m]                       [Forks and get]                                         [????] [????][Pass][????][????][????] [#]]
+    [[do_test_fork]                                     [Forks a nullary function and get]                      [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_fork_1]                                   [Forks a unary function and get]                        [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_fork_1_m]                                 [Forks a unary function and get]                        [????] [????][Pass][????][????][????] [#]]
+    [[do_test_creation_through_functor]                 [Forks a functor]                                       [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_creation_through_reference_wrapper]       [Forks a reference wrapper]                             [Pass] [????][Pass][Pass][????][????] [#]]
+
+
+    [[do_test_wait]                                     [Forks and waits]                                       [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_wait_until]                               [Forks and waits until a given time]                    [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_wait_for]                                 [Forks and waits for a given time]                      [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_get]                                      [Forks and get ]                                        [????] [----][Pass][????][????][????] [#]]
+    [[do_test_wait_all]                                 [Forks several and waits all]                           [Pass] [----][Pass][Pass][????][????] [#]]
+    [[do_test_wait_all_until]                           [Forks several and waits all until a given time]        [????] [----][Pass][Pass][????][????] [#]]
+    [[do_test_wait_all_for]                             [Forks several and waits all for a given time]          [????] [----][????][????][????][????] [#]]
+    [[do_test_set_all]                                  [Forks several and get all using set_all]               [Pass] [----][Pass][Pass][????][????] [#]]
+    [[do_test_get_all]                                  [Forks several and get all]                             [Pass] [----][Fail][Pass][????][????] [#]]
+    [[do_test_wait_for_all]                             [wait for all]                                          [Pass] [----][Pass][Pass][????][????] [#]]
+    [[do_test_wait_for_any]                             [waits for any]                                         [Fail] [----][Pass][Pass][????][????] [#]]
+    [[do_test_wait_for_any_fusion_sequence]             [Wait for any in a fusion sequence]                     [Fail] [????][????][Pass][????][????] [#]]
+
+    [[do_test_member_fork_detach]                       [Forks and detach]                                      [Fail] [????][----][Pass][????][????] [#]]
+    [[do_test_thread_interrupts_at_interruption_point]  [Interrupt]                                             [Pass] [????][----][Pass][????][????] [#]]
+    [[do_test_join]                                     [Forks and join]                                        [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_join_until]                               [Forks and joins until a given time]                    [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_join_for]                                 [Forks and joins for a given time]                      [Pass] [Pass][Pass][Pass][????][????] [#]]
+    [[do_test_join_all]                                 [Forks several and join all]                            [Pass] [----][Pass][Pass][????][????] [#]]
+    [[do_test_join_all_until]                           [Forks several and join all until a given time]         [????] [----][????][????][????][????] [#]]
+    [[do_test_join_all_for]                             [Forks several and join all for a given time]           [????] [----][????][????][????][????] [#]]
+
+    [[do_test_fork_after_join]                          [Fork after some dependent ACT and then join]           [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_fork_after_wait]                          [Fork after some dependent ACT and then wait]           [Pass] [????][Pass][Pass][????][????] [#]]
+    [[do_test_fork_after_get]                           [Fork after some dependent ACT and then get the value]  [Pass] [????][Pass][Pass][????][????] [#]]
+    [[XXXXXXXXXXXXXXXXXXXXXX]                           [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX]  [XXXX] [????][????][????][????][????] [#]]
+
+]
+
+[endsect]
+
+[endsect]

Added: sandbox/interthreads/libs/interthreads/doc/tickets.qbk
==============================================================================
--- (empty file)
+++ sandbox/interthreads/libs/interthreads/doc/tickets.qbk	2009-02-08 16:31:08 EST (Sun, 08 Feb 2009)
@@ -0,0 +1,115 @@
+[/
+  (C) Copyright 2008-2009 Vicente J Botet Escriba.
+  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  Appendix F: Tickets]
+
+
+[table
+[[Kind] [Identifier]     [Description]   [Resolution] [State]  [Tests] [Version]]
+[
+    [bug]
+    [v0.1#1]
+    [basic_keep_alive example do not link]
+    [Add to the link]
+    [Closed]
+    [See basic_keep_alive.cpp example]
+    [v0.2]
+]
+[
+    [bug]
+    [v0.2#1]
+    [ae::get_all do not work yet]
+    [get_all do not work because fusion transform sequence function can not take non const sequences.
+I have emulated it using set_all and a transformation for a tuple of ACT to a tuple of result_type.
+]
+    [Closed]
+    [do_test_get_all]
+    [v0.4]
+]
+[
+    [bug]
+    [v0.2#2]
+    [Some trouble with the use of tp::pool directly, use scheduler instead]
+    [Four issues.
+* The parameter to fork on tp:pool was a const F& instead of a F.
+* Direct use of fork_all resolved for the other AE by ADL, which could not be the case fro the tp::pool.
+* fork specialization for tp::pool incorrent.
+* use of the default handle instead of asynchronous_completion_token traits class]
+    [Closed]
+    [See tp_pool test suite]
+    [v0.3.1]
+]
+
+[
+    [bug]
+    [v0.3#1]
+    [scheduler::do_test_wait_for_any do not work yet]
+    [Not reproductible]
+    [Closed]
+    [scheduler::do_test_wait_for_any]
+    [v0.3.1]
+]
+[
+    [bug]
+    [v0.3#2]
+    [scheduler::do_test_fork_after_get do not work yet]
+    [To solve this issue it enough to define boost::move for tp::task]
+    [Closed]
+    [scheduler::do_test_fork_after_get]
+    [v0.3.1]
+]
+[
+    [bug]
+    [v0.3#3]
+    [scheduler::do_test_fork_after_wait do not work yet]
+    [To solve this issue it enough to define boost::move for tp::task]
+    [Closed]
+    [scheduler::do_test_fork_after_wait]
+    [v0.3.1]
+]
+[
+    [bug]
+    [v0.3.1#1]
+    [keep alive mechanism crash when setting set_on_dead_thread before enabling the mechanism]
+    [This was due to the fact that there were no default data for the backup.]
+    [Closed]
+    [See basic_keep_alive.cpp example]
+    [v0.4]
+]
+[
+    [bug]
+    [v0.3.1#2]
+    [keep alive mechanism do not detect dead threads]
+    [We need to reset the counters only when the period is 0.]
+    [Closed]
+    [See basic_keep_alive.cpp example]
+    [v0.4]
+]
+[
+    [bug]
+    [v0.3.1#3]
+    [The set_on_dead_thread setting is not recovered by embeeding enablers/disablers]
+    [The problem is that the on_dead  and th thread pointer were stored on the backup. It is enough to store them on the ]
+    [Closed]
+    [See basic_keep_alive.cpp example]
+    [v0.4]
+]
+[
+    [bug]
+    [v0.4.0#1]
+    [xxx]
+    [xx]
+    [Open]
+    [xxx]
+    [v0.4.1]
+]
+
+]
+
+
+
+[endsect]