asioexec::completion_token & ::use_sender (#1503)

* asioexec::completion_token & ::use_sender

Adds two completion tokens for interop with Asio (either Boost.Asio or
standalone Asio).

asioexec::completion_token performs the most basic transformations
necessary to transform an Asio initiating function into a sender
factory:

- The initiating function returns a sender
- Initiation is deferred until the above-mentioned sender is connected
  and the resulting operation state is started
- The completion handler provided to the initiation (see asio::
  async_initiate) has the following properties:
  - Invocation results in the arguments thereto being sent via a value
    completion signal (this means that errors transmitted via a leading
    error_code parameter (i.e. in Asio style) are delivered via the
    value channel, see below)
  - Abandonment thereof (i.e. allowing the lifetime of the completion
    handler, and all objects transitively derived by moving therefrom,
    to end without invoking any of them) results in a stopped completion
    signal
  - Any exception thrown from any intermediate completion handler, or
    the final completion handler, is sent via an error completion signal
    with a std::exception_ptr representing that exception (this is
    accomplished by wrapping the associated executor)
  - The cancellation slot is connected to a cancellation signal which
    is sent when a stop request is received via the receiver's
    associated stop token

The fact that invocations of the completion handler are passed to the
value channel untouched reflects the design intent that the above-
described completion token perform only "the most basic transformations
necessary." This means that the full context of partial success must be
made available and since the error channel is unary this must be
transmitted in the value channel.

For a more ergonomic experience than that described above asioexec::
use_sender is also provided. This uses asioexec::completion_token to
adapt an Asio initiating function into a sender factory and wraps the
returned sender with an additional layer which performs the following
transformations to value completion signals with a leading error_code
parameter (note that when configured for standalone Asio std::error_code
is matched whereas when configured for Boost.Asio both boost::system::
error_code and std::error_code are matched):

- If that argument compares equal to errc::operation_cancelled
  transforms the value completion signal into a stopped completion
  signal, otherwise
- If that argument is truthy transforms the value completion signal into
  an error completion signal with an appropriate std::exception_ptr
  (i.e. one which points to a std::system_error for std::error_code,
  boost::system::system_error for boost::system::error_code), otherwise
- Sends the remainder of the arguments (i.e. all but the error_code) as
  a value completion signal

* add ASIO tests to the CI matrix

---------

Co-authored-by: Eric Niebler <eniebler@nvidia.com>

Author: RobertLeahy

.github/workflows/ci.cpu.yml

@@ -67,6 +67,8 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{ matrix.build }} \
             -DCMAKE_CXX_FLAGS="${{ matrix.cxxflags }}" \
             -DSTDEXEC_ENABLE_TBB:BOOL=${{ !contains(matrix.cxxflags, '-fsanitize') }} \
+            -DSTDEXEC_ENABLE_ASIO:BOOL=TRUE \
+            -DSTDEXEC_ASIO_IMPLEMENTATION:STRING=boost \
             ;
 
           # Compile
@@ -148,6 +150,8 @@ jobs:
           cmake -S. -Bbuild -GNinja \
             -DCMAKE_BUILD_TYPE=${{ matrix.build }} \
             -DCMAKE_CXX_COMPILER=${{ matrix.compiler }} \
+            -DSTDEXEC_ENABLE_ASIO:BOOL=TRUE \
+            -DSTDEXEC_ASIO_IMPLEMENTATION:STRING=boost \
             -DCMAKE_CXX_STANDARD=20
           cmake --build build/ -v
           cd build

.github/workflows/test-windows.ps1

@@ -19,6 +19,10 @@ if (Test-Path -PathType Container $BuildDirectory) {
 }
 New-Item -ItemType Directory $BuildDirectory | Out-Null
 
-Invoke-NativeCommand cmake -B $BuildDirectory -G Ninja "-DCMAKE_BUILD_TYPE=$Config" "-DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT:STRING=Embedded" .
+Invoke-NativeCommand cmake -B $BuildDirectory -G Ninja `
+	"-DCMAKE_BUILD_TYPE=$Config" `
+	"-DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT:STRING=Embedded" `
+	"-DSTDEXEC_ENABLE_ASIO:BOOL=TRUE" `
+	"-DSTDEXEC_ASIO_IMPLEMENTATION:STRING=boost" .
 Invoke-NativeCommand cmake --build $BuildDirectory
 Invoke-NativeCommand ctest --test-dir $BuildDirectory

.gitignore

@@ -15,3 +15,4 @@ callgrind.*
 a.out
 *.code-workspace
 sanitizer-ignorelist.txt
+/include/asioexec/asio_config.hpp

CMakeLists.txt

@@ -433,6 +433,13 @@ if(STDEXEC_ENABLE_ASIO)
     set(STDEXEC_ASIO_CONFIG_FILE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/include/execpools/asio)
     configure_file(include/execpools/asio/asio_config.hpp.in ${STDEXEC_ASIO_CONFIG_FILE_PATH}/asio_config.hpp)
 
+    set(ASIOEXEC_USES_BOOST ${STDEXEC_ASIO_USES_BOOST})
+    set(ASIOEXEC_USES_STANDALONE ${STDEXEC_ASIO_USES_STANDALONE})
+
+    file(GLOB_RECURSE asioexec_sources include/asioexec/*.hpp)
+    set(ASIOEXEC_ASIO_CONFIG_FILE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/include/asioexec)
+    configure_file(include/asioexec/asio_config.hpp.in ${ASIOEXEC_ASIO_CONFIG_FILE_PATH}/asio_config.hpp)
+
     if(${STDEXEC_ASIO_USES_BOOST})
       set(BOOST_ENABLE_COMPATIBILITY_TARGETS TRUE)
       rapids_cpm_find(Boost 1.86.0
@@ -449,6 +456,16 @@ if(STDEXEC_ENABLE_ASIO)
           STDEXEC::stdexec
           Boost::boost
       )
+
+      add_library(asioexec_boost INTERFACE ${asioexec_sources})
+      list(APPEND stdexec_export_targets asioexec_boost)
+      add_library(STDEXEC::asioexec_boost ALIAS asioexec_boost)
+
+      target_link_libraries(asioexec_boost
+          INTERFACE
+          STDEXEC::stdexec
+          Boost::boost
+      )
     elseif(${STDEXEC_ASIO_USES_STANDALONE})
       include(cmake/import_standalone_asio.cmake)
       import_standalone_asio(
@@ -464,6 +481,16 @@ if(STDEXEC_ENABLE_ASIO)
           STDEXEC::stdexec
           asio
       )
+
+      add_library(asioexec_asio INTERFACE ${asioexec_sources})
+      list(APPEND stdexec_export_targets asioexec_asio)
+      add_library(STDEXEC::asioexec_asio ALIAS asioexec_asio)
+
+      target_link_libraries(asioexec_asio
+          INTERFACE
+          STDEXEC::stdexec
+          asio
+      )
     else()
       message(FATAL_ERROR "ASIO implementation is not configured")
     endif()

include/asioexec/asio_config.hpp.in

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ *                         Copyright (c) 2025 Robert Leahy. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ * Licensed under the Apache License, Version 2.0 with LLVM Exceptions (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://llvm.org/LICENSE.txt
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#cmakedefine01 ASIOEXEC_USES_STANDALONE
+#cmakedefine01 ASIOEXEC_USES_BOOST
+
+#if ASIOEXEC_USES_BOOST
+#  include <boost/asio.hpp>
+#  include <boost/system/errc.hpp>
+#  include <boost/system/error_code.hpp>
+#  include <boost/system/system_error.hpp>
+#  define ASIOEXEC_ASIO_NAMESPACE boost::asio
+#elif ASIOEXEC_USES_STANDALONE
+#  include <system_error>
+#  include <asio.hpp>
+#  define ASIOEXEC_ASIO_NAMESPACE asio
+#endif
+
+namespace asioexec {
+#if ASIOEXEC_USES_BOOST
+  namespace asio_impl = ::boost::asio;
+  using error_code = ::boost::system::error_code;
+  using error_condition = ::boost::system::error_condition;
+  namespace errc = ::boost::system::errc;
+  using system_error = ::boost::system::system_error;
+#elif ASIOEXEC_USES_STANDALONE
+  namespace asio_impl = ::asio;
+  using error_code = std::error_code;
+  using error_condition = std::error_condition;
+  using errc = std::errc;
+  using system_error = std::system_error;
+#endif
+}