added immediate_executor support.

include/boost/beast/_experimental/http/icy_stream.hpp

@@ -212,11 +212,13 @@ class icy_stream
           std::size_t bytes_transferred           // Number of bytes read.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_read_some` operation may not read all of the requested number of
         bytes. Consider using the function `net::async_read` if you need
         to ensure that the requested amount of data is read before the asynchronous
@@ -295,11 +297,13 @@ class icy_stream
           std::size_t bytes_transferred     // Number of bytes written.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-        
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_write_some` operation may not transmit all of the data to
         the peer. Consider using the function `net::async_write` if you need
         to ensure that all data is written before the asynchronous operation completes.

include/boost/beast/_experimental/test/stream.hpp

@@ -23,7 +23,6 @@
 #include <boost/asio/executor_work_guard.hpp>
 #include <boost/asio/any_io_executor.hpp>
 #include <boost/asio/io_context.hpp>
-#include <boost/asio/post.hpp>
 #include <boost/assert.hpp>
 #include <boost/shared_ptr.hpp>
 #include <boost/weak_ptr.hpp>
@@ -454,11 +453,13 @@ class basic_stream
             std::size_t bytes_transferred   // Number of bytes read.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_read_some` operation may not read all of the requested number of
         bytes. Consider using the function `net::async_read` if you need
         to ensure that the requested amount of data is read before the asynchronous
@@ -534,11 +535,13 @@ class basic_stream
             std::size_t bytes_transferred   // Number of bytes written.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_write_some` operation may not transmit all of the data to
         the peer. Consider using the function `net::async_write` if you need
         to ensure that all data is written before the asynchronous operation completes.

include/boost/beast/core/async_base.hpp

@@ -18,10 +18,12 @@
 #include <boost/beast/core/detail/work_guard.hpp>
 #include <boost/asio/associated_allocator.hpp>
 #include <boost/asio/associated_executor.hpp>
+#include <boost/asio/associated_immediate_executor.hpp>
 #include <boost/asio/bind_executor.hpp>
 #include <boost/asio/handler_alloc_hook.hpp>
 #include <boost/asio/handler_continuation_hook.hpp>
 #include <boost/asio/handler_invoke_hook.hpp>
+#include <boost/asio/dispatch.hpp>
 #include <boost/asio/post.hpp>
 #include <boost/core/exchange.hpp>
 #include <boost/core/empty_value.hpp>
@@ -30,6 +32,7 @@
 namespace boost {
 namespace beast {
 
+
 /** Base class to assist writing composed operations.
 
     A function object submitted to intermediate initiating functions during
@@ -207,7 +210,25 @@ class async_base
                 >::type;
 #endif
 
-private:
+    /** The type of the immediate executor associated with this object.
+
+    If a class derived from @ref boost::beast::async_base is a completion
+    handler, then the associated immediage executor of the derived class will
+    be this type.
+*/
+    using immediate_executor_type =
+#if BOOST_BEAST_DOXYGEN
+        __implementation_defined__;
+#else
+        typename
+        net::associated_immediate_executor<
+            Handler,
+            typename detail::select_work_guard_t<Executor1>::executor_type
+                >::type;
+#endif
+
+
+  private:
 
     virtual
     void
@@ -309,15 +330,29 @@ class async_base
             h_, wg1_.get_executor());
     }
 
-    /** The type of cancellation_slot associated with this object.
-
-        If a class derived from @ref async_base is a completion
-        handler, then the associated cancellation_slot of the
-        derived class will be this type.
+    /** Returns the executor associated with this object.
 
-        The default type is a filtering cancellation slot,
-        that only allows terminal cancellation.
+        If a class derived from @ref boost::beast::async_base is a completion
+        handler, then the object returned from this function will be used
+        as the associated executor of the derived class.
     */
+    immediate_executor_type
+    get_immediate_executor() const noexcept
+    {
+      return net::get_associated_immediate_executor(
+          h_, wg1_.get_executor());
+    }
+
+
+  /** The type of cancellation_slot associated with this object.
+
+      If a class derived from @ref async_base is a completion
+      handler, then the associated cancellation_slot of the
+      derived class will be this type.
+
+      The default type is a filtering cancellation slot,
+      that only allows terminal cancellation.
+  */
     using cancellation_slot_type =
             beast::detail::filtering_cancellation_slot<net::associated_cancellation_slot_t<Handler>>;
 
@@ -373,7 +408,9 @@ class async_base
         is invoked.
 
         @param is_continuation If this value is `false`, then the
-        handler will be submitted to the executor using `net::post`.
+        handler will be submitted to the to the immediate executor using
+        `net::dispatch`. If the handler has no immediate executor,
+        this will submit to the executor via `net::post`.
         Otherwise the handler will be invoked as if by calling
         @ref boost::beast::async_base::complete_now.
 
@@ -388,14 +425,12 @@ class async_base
         this->before_invoke_hook();
         if(! is_continuation)
         {
-            auto const ex = get_executor();
-            net::post(
-                wg1_.get_executor(),
-                net::bind_executor(
-                  ex,
-                  beast::bind_front_handler(
-                      std::move(h_),
-                      std::forward<Args>(args)...)));
+            auto const ex = this->get_immediate_executor();
+            net::dispatch(
+                ex,
+                beast::bind_front_handler(
+                    std::move(h_),
+                    std::forward<Args>(args)...));
             wg1_.reset();
         }
         else

include/boost/beast/core/basic_stream.hpp

@@ -928,10 +928,13 @@ class basic_stream
             error_code ec         // Result of operation
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
 
         @par Per-Operation Cancellation
 
@@ -993,10 +996,13 @@ class basic_stream
             typename Protocol::endpoint const& endpoint
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
 
         @par Per-Operation Cancellation
 
@@ -1079,11 +1085,13 @@ class basic_stream
             typename Protocol::endpoint const& endpoint
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @par Example
         The following connect condition function object can be used to output
         information about the individual connection attempts:
@@ -1173,11 +1181,13 @@ class basic_stream
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1244,11 +1254,13 @@ class basic_stream
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1377,11 +1389,13 @@ class basic_stream
             std::size_t bytes_transferred   // Number of bytes read.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_read_some` operation may not receive all of the requested
         number of bytes. Consider using the function `net::async_read` if you need
         to ensure that the requested amount of data is read before the asynchronous
@@ -1511,11 +1525,13 @@ class basic_stream
             std::size_t bytes_transferred   // Number of bytes written.
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.
         @note The `async_write_some` operation may not transmit all of the requested
         number of bytes. Consider using the function `net::async_write` if you need
         to ensure that the requested amount of data is sent before the asynchronous

include/boost/beast/core/buffered_read_stream.hpp

@@ -256,11 +256,13 @@ class buffered_read_stream
             std::size_t bytes_transferred // number of bytes transferred
         );
         @endcode        
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-    */
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.    */
     template<
         class MutableBufferSequence,
         BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
@@ -335,11 +337,13 @@ class buffered_read_stream
             std::size_t bytes_transferred // number of bytes transferred
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
-        this function. Invocation of the handler will be performed in a
-        manner equivalent to using `net::post`.
-    */
+        If the handler has an associated immediate executor,
+        an immediate completion will be dispatched to it.
+        Otherwise, the handler will not be invoked from within
+        this function. Invocation of the handler will be performed
+        by dispatching to the immediate executor. If no
+        immediate executor is specified, this is equivalent
+        to using `net::post`.    */
     template<
         class ConstBufferSequence,
         BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =

include/boost/beast/core/buffers_generator.hpp

@@ -167,10 +167,11 @@ write(
         std::size_t bytes_transferred   // the number of bytes written to the stream
     );
     @endcode
-    Regardless of whether the asynchronous operation completes
-    immediately or not, the handler will not be invoked from
-    within this function. Invocation of the handler will be
-    performed in a manner equivalent to using `net::post`.
+    If the handler has an associated immediate executor,
+    an immediate completion will be dispatched to it.
+    Otherwise, the handler will not be invoked from within
+    this function. Invocation of the handler will be performed in a
+    manner equivalent to using `net::post`.
 
     @see BuffersGenerator
 */