[Boost-commit] svn:boost r59104 - in trunk: boost/asio libs/asio/doc

Subject: [Boost-commit] svn:boost r59104 - in trunk: boost/asio libs/asio/doc
From: chris_at_[hidden]
Date: 2010-01-17 16:48:18

Author: chris_kohlhoff
Date: 2010-01-17 16:48:17 EST (Sun, 17 Jan 2010)
New Revision: 59104
URL: http://svn.boost.org/trac/boost/changeset/59104

Log:
Document ordering of handlers in strands. Fix error in streambuf snippet.

Text files modified: 
   trunk/boost/asio/basic_streambuf.hpp |     2                                         
   trunk/boost/asio/strand.hpp          |    40 +++++++++++++++++                       
   trunk/libs/asio/doc/reference.qbk    |    92 +++++++++++++++++++++++++++++++++++++++ 
   3 files changed, 131 insertions(+), 3 deletions(-)

Modified: trunk/boost/asio/basic_streambuf.hpp
==============================================================================
--- trunk/boost/asio/basic_streambuf.hpp	(original)
+++ trunk/boost/asio/basic_streambuf.hpp	2010-01-17 16:48:17 EST (Sun, 17 Jan 2010)
@@ -96,7 +96,7 @@
  * boost::asio::streambuf b;
  *
  * // reserve 512 bytes in output sequence
- * boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+ * boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);
  *
  * size_t n = sock.receive(bufs);
  *

Modified: trunk/boost/asio/strand.hpp
==============================================================================
--- trunk/boost/asio/strand.hpp	(original)
+++ trunk/boost/asio/strand.hpp	2010-01-17 16:48:17 EST (Sun, 17 Jan 2010)
@@ -30,6 +30,46 @@
  * handlers with the guarantee that none of those handlers will execute
  * concurrently.
  *
+ * @par Order of handler invocation
+ * Given:
+ *
+ * @li a strand object @c s
+ *
+ * @li an object @c a meeting completion handler requirements
+ *
+ * @li an object @c a1 which is an arbitrary copy of @c a made by the
+ * implementation
+ *
+ * @li an object @c b meeting completion handler requirements
+ *
+ * @li an object @c b1 which is an arbitrary copy of @c b made by the
+ * implementation
+ *
+ * if any of the following conditions are true:
+ *
+ * @li @c s.post(a) happens-before @c s.post(b)
+ * 
+ * @li @c s.post(a) happens-before @c s.dispatch(b), where the latter is
+ * performed outside the strand
+ * 
+ * @li @c s.dispatch(a) happens-before @c s.post(b), where the former is
+ * performed outside the strand
+ * 
+ * @li @c s.dispatch(a) happens-before @c s.dispatch(b), where both are
+ * performed outside the strand
+ *   
+ * then @c asio_handler_invoke(a1, &a1) happens-before
+ * @c asio_handler_invoke(b1, &b1).
+ * 
+ * Note that in the following case:
+ * @code async_op_1(..., s.wrap(a));
+ * async_op_2(..., s.wrap(b)); @endcode
+ * the completion of the first async operation will perform @c s.dispatch(a),
+ * and the second will perform @c s.dispatch(b), but the order in which those
+ * are performed is unspecified. That is, you cannot state whether one
+ * happens-before the other. Therefore none of the above conditions are met and
+ * no ordering guarantee is made.
+ *
  * @par Thread Safety
  * @e Distinct @e objects: Safe._at_n
  * @e Shared @e objects: Safe.

Modified: trunk/libs/asio/doc/reference.qbk
==============================================================================
--- trunk/libs/asio/doc/reference.qbk	(original)
+++ trunk/libs/asio/doc/reference.qbk	2010-01-17 16:48:17 EST (Sun, 17 Jan 2010)
@@ -30284,7 +30284,7 @@
    boost::asio::streambuf b;
 
    // reserve 512 bytes in output sequence
-   boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+   boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);
 
    size_t n = sock.receive(bufs);
 
@@ -37994,6 +37994,50 @@
 The [link boost_asio.reference.io_service__strand `io_service::strand`] class provides the ability to post and dispatch handlers with the guarantee that none of those handlers will execute concurrently.
 
 
+[heading Order of handler invocation]
+  
+Given:
+
+
+* a strand object s 
+
+
+* an object a meeting completion handler requirements
+
+
+* an object a1 which is an arbitrary copy of a made by the implementation
+
+
+* an object b meeting completion handler requirements
+
+
+* an object b1 which is an arbitrary copy of b made by the implementation
+
+if any of the following conditions are true:
+
+
+* s.post(a) happens-before s.post(b) 
+
+
+* s.post(a) happens-before s.dispatch(b), where the latter is performed outside the strand
+
+
+* s.dispatch(a) happens-before s.post(b), where the former is performed outside the strand
+
+
+* s.dispatch(a) happens-before s.dispatch(b), where both are performed outside the strand
+
+then `asio_handler_invoke(a1, &a1)` happens-before `asio_handler_invoke(b1, &b1)`.
+
+Note that in the following case: 
+
+   async_op_1(..., s.wrap(a));
+   async_op_2(..., s.wrap(b)); 
+
+
+the completion of the first async operation will perform `s.dispatch(a)`, and the second will perform `s.dispatch(b)`, but the order in which those are performed is unspecified. That is, you cannot state whether one happens-before the other. Therefore none of the above conditions are met and no ordering guarantee is made.
+
+
 [heading Thread Safety]
   
 [*Distinct] [*objects:] Safe.
@@ -64243,6 +64287,50 @@
 The [link boost_asio.reference.io_service__strand `io_service::strand`] class provides the ability to post and dispatch handlers with the guarantee that none of those handlers will execute concurrently.
 
 
+[heading Order of handler invocation]
+  
+Given:
+
+
+* a strand object s 
+
+
+* an object a meeting completion handler requirements
+
+
+* an object a1 which is an arbitrary copy of a made by the implementation
+
+
+* an object b meeting completion handler requirements
+
+
+* an object b1 which is an arbitrary copy of b made by the implementation
+
+if any of the following conditions are true:
+
+
+* s.post(a) happens-before s.post(b) 
+
+
+* s.post(a) happens-before s.dispatch(b), where the latter is performed outside the strand
+
+
+* s.dispatch(a) happens-before s.post(b), where the former is performed outside the strand
+
+
+* s.dispatch(a) happens-before s.dispatch(b), where both are performed outside the strand
+
+then `asio_handler_invoke(a1, &a1)` happens-before `asio_handler_invoke(b1, &b1)`.
+
+Note that in the following case: 
+
+   async_op_1(..., s.wrap(a));
+   async_op_2(..., s.wrap(b)); 
+
+
+the completion of the first async operation will perform `s.dispatch(a)`, and the second will perform `s.dispatch(b)`, but the order in which those are performed is unspecified. That is, you cannot state whether one happens-before the other. Therefore none of the above conditions are met and no ordering guarantee is made.
+
+
 [heading Thread Safety]
   
 [*Distinct] [*objects:] Safe.
@@ -65167,7 +65255,7 @@
    boost::asio::streambuf b;
 
    // reserve 512 bytes in output sequence
-   boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+   boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);
 
    size_t n = sock.receive(bufs);