First step toward immediate_executor.

asio::async_compose doesn't know the immediate_executor however, so this seems somewhat incomplete, if not pointless.

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

@@ -212,11 +212,11 @@ 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
+        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`.
-
         @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 +295,11 @@ 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
+        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`.
-        
         @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

@@ -454,11 +454,11 @@ 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
+        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`.
-
         @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 +534,11 @@ 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
+        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`.
-
         @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>
@@ -207,7 +209,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 +329,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>>;
 
@@ -388,14 +422,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 = 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,8 +928,9 @@ 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
+        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`.
 
@@ -993,8 +994,9 @@ 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
+        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`.
 
@@ -1079,11 +1081,11 @@ 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
+        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`.
-
         @par Example
         The following connect condition function object can be used to output
         information about the individual connection attempts:
@@ -1173,11 +1175,11 @@ class basic_stream
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
+        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`.
-
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1244,11 +1246,11 @@ class basic_stream
             Iterator iterator
         );
         @endcode
-        Regardless of whether the asynchronous operation completes
-        immediately or not, the handler will not be invoked from within
+        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`.
-
         @par Per-Operation Cancellation
 
         This asynchronous operation supports cancellation for the following
@@ -1377,11 +1379,11 @@ 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
+        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`.
-
         @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 +1513,11 @@ 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
+        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`.
-
         @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,11 @@ 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
+        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`.
-    */
+        manner equivalent to using `net::post`.    */
     template<
         class MutableBufferSequence,
         BOOST_BEAST_ASYNC_TPARAM2 ReadHandler =
@@ -335,11 +335,11 @@ 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
+        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`.
-    */
+        manner 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
 */

include/boost/beast/core/detail/read.hpp

@@ -210,10 +210,11 @@ read(
                                             // prior to the error.
     );
     @endcode
-    Regardless of whether the asynchronous operation completes
-    immediately or not, the handler will not be invoked from within
+    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`.
+    manner equivalent to using `net::post`..
 */
 template<
     class AsyncReadStream,

include/boost/beast/core/detect_ssl.hpp

@@ -308,10 +308,11 @@ detect_ssl(
         bool result                 // The result of the detector
     );
     @endcode
-    Regardless of whether the asynchronous operation completes
-    immediately or not, the handler will not be invoked from within
+    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`.
+    manner equivalent to using `net::post`..
 */
 template<
     class AsyncReadStream,

include/boost/beast/core/flat_stream.hpp

@@ -241,11 +241,11 @@ class flat_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
+        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`.
-        
         @note The `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
@@ -323,11 +323,11 @@ class flat_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
+        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`.
-        
         @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.