diff --git a/acknowledgements.html b/acknowledgements.html index 5b483158..e9214745 100644 --- a/acknowledgements.html +++ b/acknowledgements.html @@ -457,6 +457,8 @@

Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -494,7 +496,7 @@

    Acknowledgements

    diff --git a/advanced_examples.html b/advanced_examples.html new file mode 100644 index 00000000..6fecb050 --- /dev/null +++ b/advanced_examples.html @@ -0,0 +1,567 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    Advanced examples

    +
    +
    +

    More examples are provided in the repository as code only. All examples are listed below.

    +
    + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 4. All examples

    example/http.cpp

    An http client that performs a single http get request.

    example/outcome.cpp

    Using the boost.outcome coroutine types.

    example/python.cpp & example/python.py

    Uisng nanobind to integrate async with python. +It uses python’s asyncio as executor and allows C++ to co_await python functions et vice versa.

    example/signals.cpp

    Adopting boost.signals2 into an awaitable type (single threaded).

    example/spsc.cpp

    Creating a boost.lockfree based & awaitable spsc_queue (multi threaded).

    example/thread.cpp

    Using worker threads with asio’s `concurrent_channel.

    example/thread_pool.cpp

    Using an asio::thread_pool and spawning tasks onto them.

    example/delay.cpp

    The example used by the delay section

    example/delay_op.cpp

    The example used by the delay op section

    example/echo_server.cpp

    The example used by the echo server section

    example/ticker.cpp

    The example used by the price ticker section

    example/channel.cpp

    The example used by the channel reference

    +
    +
    +
    +

    ← Previous: Generator with push value | ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: Design →

    +
    +
    + + + \ No newline at end of file diff --git a/associators.html b/associators.html new file mode 100644 index 00000000..3c25a80f --- /dev/null +++ b/associators.html @@ -0,0 +1,773 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Associators

    +
    +
    +

    async uses the associator concept of asio, but simplifies it. +That is, it has three associators that are member functions of an awaiting promise.

    +
    +
    +
      +
    • +

      const executor_type & get_executor() (always executor, must return by const ref)

      +
      • +
    • +

      allocator_type get_allocator() (always pmr::polymorphic_allocator<void>)

      +
      • +
    • +

      cancellation_slot_type get_cancellation_slot() (must have the same IF as asio::cancellation_slot)

      +
      • +
    +
    +
    +

    async uses concepts to check if those are present in its await_suspend functions.

    +
    +
    +

    That way custom coroutines can support cancellation, executors etc..

    +
    +
    +

    In a custom awaitable you can obtain them like this:

    +
    +
    +
    +
    struct my_awaitable
+{
+    bool await_ready();
+    template<typename T>
+    void await_suspend(std::corutine_handle<P> h)
+    {
+        if constexpr (requires  (Promise p) {p.get_executor();})
+            handle_executor(h.promise().get_executor();
+
+        if constexpr (requires (Promise p) {p.get_cancellation_slot();})
+            if ((cl = h.promise().get_cancellation_slot()).is_connected())
+                cl.emplace<my_cancellation>();
+    }
+
+    void await_resume();
+};
    +
    +
    +
    +
    +
    +

    ← Previous: interrupt_await | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Threading →

    +
    +
    + + + \ No newline at end of file diff --git a/async_for.html b/async_for.html new file mode 100644 index 00000000..c26be4b5 --- /dev/null +++ b/async_for.html @@ -0,0 +1,775 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/async_for.hpp

    +
    +
    +

    For types like generators a BOOST_ASYNC_FOR macro is provided, to emulate an async for loop.

    +
    +
    +
    +
    async::generator<int> gen();
+
+async::main co_main(int argc, char * argv[])
+{
+    BOOST_ASYNC_FOR(auto i, gen())
+        printf("Generated value %d\n", i);
+
+    co_return 0;
+}
    +
    +
    +
    +

    The requirement is that the awaitable used in the for loop has an operator bool to check if it +can be awaited again. This is the case for generator and promise.

    +
    +
    +
    +
    +

    ← Previous: async/result.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/error.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/async_operation.html b/async_operation.html new file mode 100644 index 00000000..e0d5af5e --- /dev/null +++ b/async_operation.html @@ -0,0 +1,911 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/op.hpp

    +
    +
    +

    An async operation is an awaitable wrapping an asio operation.

    +
    +
    +

    E.g. this is an async_operation with the completion signature void().

    +
    +
    +
    +
    auto op = asio::post(ctx, async::use_op);
    +
    +
    +
    +

    Or the async_operation can be templated like this:

    +
    +
    +
    +
    auto op = [&ctx](auto token) {return asio::post(ctx, std::move(token)); };
    +
    +
    +
    +

    use_op

    +
    +

    The use_op token is the direct to create an op, +i.e. using async::use_op as the completion token will create the required awaitable.

    +
    +
    +

    It also supports defaults_on so that async_ops can be awaited without the token:

    +
    +
    +
    +
    auto tim = async::use_op.as_default_on(asio::steady_timer{co_await async::this_coro::executor});
+co_await tim.async_wait();
    +
    +
    +
    +

    Depending on the completion signature the co_await expression may throw.

    +
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    SignatureReturn typeException

    void()

    void

    noexcept

    void(T)

    T

    noexcept

    void(T…​)

    std::tuple<T…​>

    noexcept

    void(system::error_code, T)

    T

    system::system_error

    void(system::error_code, T…​)

    std::tuple<T…​>

    system::system_error

    void(std::exception_ptr, T)

    T

    any exception

    void(std::exception_ptr, T…​)

    std::tuple<T…​>

    any exception

    +
    + + + + + +
    + + +use_op will never complete immediately, i.e. await_ready will always return false, but always suspend the coroutine. +
    +
    +
    +
    +

    Hand coded Operations

    +
    +

    Operations are a more advanced implementation of the async/op.hpp feature.

    +
    +
    +

    This library makes it easy to create asynchronous operations with an early completion condition, +i.e. a condition that avoids suspension of coroutines altogether.

    +
    +
    +

    We can for example create a wait_op that does nothing if the timer is already expired.

    +
    +
    +
    +
    struct wait_op : async::op<system::error_code> (1)
+{
+  asio::steady_timer & tim;
+
+  wait_op(asio::steady_timer & tim) : tim(tim) {}
+
+  bool ready(async::handler<system::error_code> ) (2)
+  {
+    if (tim.expiry() < std::chrono::steady_clock::now())
+        h(system::error_code{});
+  }
+  void initiate(async::completion_handler<system::error_code> complete) (3)
+  {
+    tim.async_wait(std::move(complete));
+  }
+};
    +
    +
    +
    + + + + + + + + + + + + + +
    1Inherit op with the matching signature await_transform picks it up
    2Check if the operation is ready - called from await_ready
    3Initiate the async operation if its not ready.
    +
    +
    +
    +
    +
    +

    ← Previous: async/detached.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/concepts.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/async_programming.html b/async_programming.html new file mode 100644 index 00000000..8b8f68a8 --- /dev/null +++ b/async_programming.html @@ -0,0 +1,793 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Async programming

    +
    +
    +

    Asynchronous programming generally refers to a style of programming +that allows tasks to be run in the background, while the other works is performed.

    +
    +
    +

    Imagine if you will a get-request function that performs a +full http request including connecting & ssl handshakes etc.

    +
    +
    +
    +
    std::string http_get(std:string_view url);
+
+int main(int argc, char * argv[])
+{
+    auto res = http_get("https://boost.org");
+    printf("%s", res.c_str());
+    return 0;
+}
    +
    +
    +
    +

    The above code would be traditional synchronous programming. If we want to perform +two requests in parallel we would need to create another thread to run another thread +with synchronous code.

    +
    +
    +
    +
    std::string http_get(std:string_view url);
+
+int main(int argc, char * argv[])
+{
+    std::string other_res;
+
+    std::thread thr{[&]{ other_res = http_get("https://cppalliance.org"); }};
+    auto res = http_get("https://boost.org");
+    thr.join();
+
+    printf("%s", res.c_str());
+    printf("%s", other_res.c_str());
+    return 0;
+}
    +
    +
    +
    +

    This works, but our program will spend most of the time waiting for input. +Operating systems provide APIs that allow IO to be performed asynchronously, +and libraries such as boost.asio +provide portable ways to manage asynchronous operations. +Asio itself does not dictate a way to handle the completions. +This library (boost.async) provides a way to manage this all through coroutines/awaitables.

    +
    +
    +
    +
    async::promise<std::string> http_async_get(std:string_view url);
+
+async::main co_main(int argc, char * argv[])
+{
+    auto [res, other_res] =
+            async::join(
+                http_async_get(("https://boost.org"),
+                http_async_get(("https://cppalliance.org")
+            );
+
+    printf("%s", res.c_str());
+    printf("%s", other_res.c_str());
+    return 0;
+}
    +
    +
    +
    +

    In the above code the asynchronous function to perform the request +takes advantage of the operating system APIs so that the actual IO doesn’t block. +This means that while we’re waiting for both functions to complete, +the operations are interleaved and non-blocking. +At the same time async provides the coroutine primitives that keep us out of callback hell.

    +
    +
    +
    +
    +

    ↑ Up: Coroutine Primer | ⌂ Home: Documentation boost.async | Next: Coroutines →

    +
    +
    + + + \ No newline at end of file diff --git a/awaitables.html b/awaitables.html new file mode 100644 index 00000000..54f2e163 --- /dev/null +++ b/awaitables.html @@ -0,0 +1,810 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Awaitables

    +
    +
    +

    Awaitables are types that can be used in a co_await expression.

    +
    +
    +
    +
    struct awaitable_prototype
+{
+    bool await_ready();
+
+    template<typename T>
+    see_below await_suspend(std::coroutine_handle<T>);
+
+    return_type  await_resume();
+};
    +
    +
    +
    + + + + + +
    + + +Type will be implicitly converted into an awaitable if there is an operator co_await call available. +This documentation will use awaitable to include these types, +and "actual_awaitable" to refer to type conforming to the above prototype. +
    +
    +
    +
    +Diagram +
    +
    +
    +

    In a co_await expression the waiting coroutine will first invoke +await_ready to check if the coroutine needs to suspend. +When ready, it goes directly to await_resume to get the value, +as there is no suspension needed. +Otherwise, it will suspend itself and call await_suspend with a +std::coroutine_handle to its own promise.

    +
    +
    + + + + + +
    + + +std::coroutine_handle<void> can be used for type erasure. +
    +
    +
    +

    The return_type is the result type of the co_await expression, e.g. int:

    +
    +
    +
    +
    int i = co_await awaitable_with_int_result();
    +
    +
    +
    +

    The return type of the await_suspend can be three things:

    +
    +
    +
      +
    • +

      void

      +
      • +
    • +

      bool

      +
      • +
    • +

      std::coroutine_handle<U>

      +
      • +
    +
    +
    +

    If it is void the awaiting coroutine remains suspended. If it is bool, +the value will be checked, and if falls, the awaiting coroutine will resume right away.

    +
    +
    +

    If a std::coroutine_handle is returned, this coroutine will be resumed. +The latter allows await_suspend to return the handle passed in, +being effectively the same as returning false.

    +
    +
    +

    If the awaiting coroutine gets re-resumed right away, i.e. after calling await_resume, +it is referred to as "immediate completion" within this library. +This is not to be confused with a non-suspending awaitable, i.e. one that returns true from await_ready.

    +
    +
    +
    +
    +

    ← Previous: Coroutines | ↑ Up: Coroutine Primer | ⌂ Home: Documentation boost.async | Next: Event Loops →

    +
    +
    + + + \ No newline at end of file diff --git a/benchmarks.html b/benchmarks.html index db2d4b4b..700d6b1b 100644 --- a/benchmarks.html +++ b/benchmarks.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -690,6 +692,8 @@

    Documentation boost.async

  • Channels
    • +
  • Operation Allocations +
  • Compiler support @@ -722,7 +726,7 @@

    Posting to an executor

    - +@@ -785,7 +789,7 @@

    Running noop coroutine in parallel

    Table 5. results for 50M times in msTable 6. results for 50M times in ms
    - +@@ -832,7 +836,7 @@

    Immediate

    Table 6. results for 3M times in msTable 7. results for 3M times in ms
    - +@@ -867,13 +871,13 @@

    Immediate

    Channels

    -

    As In this benchmark asio::experimental::channel and async::channel get compared.

    +

    In this benchmark asio::experimental::channel and async::channel get compared.

    -

    This si similar to the parallel test, but uses the async::channel instead.

    +

    This is similar to the parallel test, but uses the async::channel instead.

    Table 7. result for 10M times in msTable 8. result for 10M times in ms
    - +@@ -905,6 +909,50 @@

    Channels

    Table 8. result of running the test 3M times in msTable 9. result of running the test 3M times in ms
    +
    +

    Operation Allocations

    +
    +

    This benchmark compares the different possible solutions for the associated allocator of asynchronous operations

    +
    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 10. result of running the test 2M times in ms
    gccclang

    std::allocator

    1136

    1139

    async::monotonic

    1149

    1270

    pmr::monotonic

    1164

    1173

    async::sbo

    1021

    1060

    +

    The latter method is used internally by async.

    +
    @@ -914,7 +962,7 @@

    Channels

    diff --git a/cancellation.html b/cancellation.html new file mode 100644 index 00000000..d0ab3532 --- /dev/null +++ b/cancellation.html @@ -0,0 +1,542 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    cancellation

    +
    +
    +

    async uses implicit cancellation based on asio::cancellation_signal. +This is mostly used implicitly (e.g. with select), +so that there is very little explicit use in the examples.

    +
    +
    + + + + + +
    + + +If you write custom coroutine it must return a cancellation_slot from a +get_cancellation_slot function in order to be able to cancel other operations. +
    +
    +
    + + + + + +
    + + +If you write a custom awaitable, it can use that function in await_suspend to receive cancellation signals. +
    +
    +
    +
    +
    +

    ← Previous: polymorphic memory resource | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Promise →

    +
    +
    + + + \ No newline at end of file diff --git a/channel.html b/channel.html new file mode 100644 index 00000000..5557adfa --- /dev/null +++ b/channel.html @@ -0,0 +1,931 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/channel.hpp

    +
    +
    +

    Channels can be used to exchange data between different coroutines +on a single thread.

    +
    +
    +

    Outline

    +
    +
    channel outline
    +
    +
    template<typename T>
+struct channel
+{
+  // create a channel with a buffer limit, executor & resource.
+  explicit
+  channel(std::size_t limit = 0u,
+          executor executor = this_thread::get_executor(),
+          pmr::memory_resource * resource = this_thread::get_default_resource());
+  // movable. moving with active operations is undefined behaviour.
+  channel(channel && ) noexcept = default;
+  channel & operator=(channel && lhs) noexcept = delete;
+
+  using executor_type = executor;
+  const executor_type & get_executor();
+
+  // Closes the channel
+  ~channel();
+  bool is_open() const;
+  // close the operation, will cancel all pending ops, too
+  void close();
+
+  // an awaitable that yields T
+  using read_op = unspecified;
+
+  // an awaitable that yields void
+  using write_op = unspecified;
+
+  // read a value to a channel
+  read_op  read();
+
+  // write a value to the channel
+  write_op write(const T  && value);
+  write_op write(const T  &  value);
+  write_op write(      T &&  value);
+  write_op write(      T  &  value);
+
+  // write a value to the channel if T is void
+
+};
    +
    +
    +
    +
    +

    Description

    +
    +

    Channels are a tool for two coroutines to communicate and synchronize.

    +
    +
    +
    +
    const std::size_t buffer_size = 2;
+channel<int> ch{exec, buffer_size};
+
+// in coroutine (1)
+co_await ch.write(42);
+
+// in coroutine (2)
+auto val = co_await ch.read();
    +
    +
    +
    + + + + + + + + + +
    1Send a value to the channel - will block until it can be sent
    2Read a value from the channel - will block until a value is awaitable.
    +
    +
    +

    Both operations maybe be blocking depending on the channel buffer size.

    +
    +
    +

    If the buffer size is zero, a read & write will need to occur at the same time, +i.e. act as a rendezvous.

    +
    +
    +

    If the buffer is not full, the write operation will not suspend the coroutine; +likewise if the buffer is not empty, the read operation will not suspend.

    +
    +
    +

    If two operations complete at once (as is always the case with an empty buffer), +the second operation gets posted to the executor for later completion.

    +
    +
    + + + + + +
    + + +A channel type can be void, in which case write takes no parameter. +
    +
    +
    +

    The channel operations can be cancelled without losing data. +This makes them usable with select.

    +
    +
    +
    +
    generator<variant2::variant<int, double>> merge(
+    channel<int> & c1,
+    channel<double> & c2)
+{
+    while (c1 && c2)
+       co_yield co_await select(c1, c2);
+}
    +
    +
    +
    +
    +

    Example

    +
    +
    +
    async::promise<void> producer(async::channel<int> & chan)
+{
+  for (int i = 0; i < 4; i++)
+    co_await chan.write(i);
+
+  chan.close();
+}
+
+async::main co_main(int argc, char * argv[])
+{
+  async::channel<int> c;
+
+  auto p = producer(c);
+  while (c.is_open())
+    std::cout << co_await c.read() << std::endl;
+
+  co_await p;
+  co_return 0;
+}
    +
    +
    +
    +

    Additionally, a channel_reader is provided to make reading channels more convenient & usable with +BOOST_ASYNC_FOR.

    +
    +
    +
    +
    async::main co_main(int argc, char * argv[])
+{
+  async::channel<int> c;
+
+  auto p = producer(c);
+  BOOST_ASYNC_FOR(int value, async::channel_reader(c))
+    std::cout << value << std::endl;
+
+  co_await p;
+  co_return 0;
+}
    +
    +
    +
    +
    +
    +
    +

    ← Previous: async/this_thread.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/with.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/channels.html b/channels.html new file mode 100644 index 00000000..0f9b5009 --- /dev/null +++ b/channels.html @@ -0,0 +1,540 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    Channels

    +
    +
    +

    As In this benchmark asio::experimental::channel and async::channel get compared.

    +
    +
    +

    This si similar to the parallel test, but uses the async::channel instead.

    +
    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 8. result of running the test 3M times in ms
    gccclang

    async

    500

    350

    awaitable

    790

    770

    stackful

    867

    907

    +
    +
    +
    +

    ← Previous: Immediate | ↑ Up: Benchmarks | ⌂ Home: Documentation boost.async | Next: Compiler support →

    +
    +
    + + + \ No newline at end of file diff --git a/compiler_support.html b/compiler_support.html index df82812f..110decef 100644 --- a/compiler_support.html +++ b/compiler_support.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -777,7 +779,7 @@

    Compiler support

    diff --git a/concepts.html b/concepts.html new file mode 100644 index 00000000..06912ea7 --- /dev/null +++ b/concepts.html @@ -0,0 +1,804 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/concepts.hpp

    +
    +
    +

    Awaitable

    +
    +

    An awaitable is an expression that can be used with co_await.

    +
    +
    +
    +
    template<typename Awaitable, typename Promise = void>
+concept awaitable_type = requires (Awaitable aw, std::coroutine_handle<Promise> h)
+{
+    {aw.await_ready()} -> std::convertible_to<bool>;
+    {aw.await_suspend(h)};
+    {aw.await_resume()};
+};
+
+template<typename Awaitable, typename Promise = void>
+concept awaitable =
+        awaitable_type<Awaitable, Promise>
+    || requires (Awaitable && aw) { {std::forward<Awaitable>(aw).operator co_await()} -> awaitable_type<Promise>;}
+    || requires (Awaitable && aw) { {operator co_await(std::forward<Awaitable>(aw))} -> awaitable_type<Promise>;};
    +
    +
    +
    + + + + + +
    + + +awaitables in this library require that the coroutine promise +return their executor by const reference if they provide one. Otherwise it’ll use this_thread::get_executor(). +
    +
    +
    +
    +

    Enable awaitables

    +
    +

    Inheriting enable_awaitables will enable a coroutine to co_await anything through await_transform +that would be co_await-able in the absence of any await_transform.

    +
    +
    +
    +
    +
    +

    ← Previous: async/op.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/this_coro.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/config.html b/config.html new file mode 100644 index 00000000..f7d9cb34 --- /dev/null +++ b/config.html @@ -0,0 +1,607 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    async/config.hpp

    +
    +
    +

    The config adder allows to config some implementation details of boost.async.

    +
    +
    +

    executor_type

    +
    +

    The executor type defaults to boost::asio::any_io_executor.

    +
    +
    +

    You can set it to boost::asio::any_io_executor by defining BOOST_ASYNC_CUSTOM_EXECUTOR +and adding a boost::async::executor type yourself.

    +
    +
    +

    Alternatively, BOOST_ASYNC_USE_IO_CONTEXT can be defined +to set the executor to boost::asio::io_context::executor_type.

    +
    +
    +
    +

    pmr

    +
    +

    Boost.async can be used with different pmr implementations, defaulting to std::pmr.

    +
    +
    +

    The following macros can be used to configure it:

    +
    +
    +
      +
    • +

      BOOST_ASYNC_USE_STD_PMR

      +
      • +
    • +

      BOOST_ASYNC_USE_BOOST_CONTAINER_PMR

      +
      • +
    • +

      BOOST_ASYNC_USE_CUSTOM_PMR

      +
      • +
    +
    +
    +

    If you define BOOST_ASYNC_USE_CUSTOM_PMR you will need to provide a boost::async::pmr namespace, +that is a drop-in replacement for std::pmr.

    +
    +
    +

    Alternatively, the pmr use can be disabled with

    +
    +
    +
      +
    • +

      BOOST_ASYNC_NO_PMR.

      +
      • +
    +
    +
    +

    In this case, async will use a non-pmr monotonic resource for the +synchronization functions (select, gather and join).

    +
    +
    +

    use_op uses a small-buffer-optimized resource which’s size can be set by defining +BOOST_ASYNC_SBO_BUFFER_SIZE and defaults to 4096 bytes.

    +
    +
    +
    +
    +
    +

    ← Previous: async/error.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/leaf.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/coroutine_primer.html b/coroutine_primer.html index 5c763510..4d762d53 100644 --- a/coroutine_primer.html +++ b/coroutine_primer.html @@ -690,6 +690,8 @@

    Documentation boost.async

    • +
  • Tour +
  • Tutorial
  • Design @@ -1037,13 +1039,13 @@

    Event Loops

    -

    ← Previous: Motivation | ↑ Up: Documentation boost.async | Next: Tutorial →

    +

    ← Previous: Motivation | ↑ Up: Documentation boost.async | Next: Tour →

    diff --git a/coroutines.html b/coroutines.html new file mode 100644 index 00000000..dd3f09b1 --- /dev/null +++ b/coroutines.html @@ -0,0 +1,856 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Coroutines

    +
    +
    +

    Coroutines are resumable functions. +Resumable means that a function can suspend, +i.e. pass the control back to the caller multiple times.

    +
    +
    +

    A regular function yields control back to the caller with the return function, where it also returns the value.

    +
    +
    +

    A coroutine on the other hand might yield control to the caller and get resumed multiple times.

    +
    +
    +

    A coroutine has three control keywords akin to co_return +(of which only co_return has to be supported).

    +
    +
    +
      +
    • +

      co_return

      +
      • +
    • +

      co_yield

      +
      • +
    • +

      co_await

      +
      • +
    +
    +
    +

    co_return

    +
    +

    This is similar to return, but marks the function as a coroutine.

    +
    +
    +
    +

    co_await

    +
    +

    The co_await expression suspends for an Awaitable, +i.e. stops execution until the awaitable resumes it.

    +
    +
    +

    E.g.:

    +
    +
    +
    +
    async::promise<void> delay(std::chrono::milliseconds);
+
+async::task<void> example()
+{
+  co_await delay(std::chrono::milliseconds(50));
+}
    +
    +
    +
    +

    A co_await expression can yield a value, depending on what it is awaiting.

    +
    +
    +
    +
    async::promise<std::string> read_some();
+
+async::task<void> example()
+{
+  std::string res = co_await read_some();
+}
    +
    +
    +
    + + + + + +
    + + +In async most coroutine primitives are also Awaitables. +
    +
    +
    +
    +

    co_yield

    +
    +

    The co_yield expression is similar to the co_await, +but it yields control to the caller and carries a value.

    +
    +
    +

    For example:

    +
    +
    +
    +
    async::generator<int> iota(int max)
+{
+  int i = 0;
+  while (i < max)
+    co_yield i++;
+
+  co_return i;
+}
    +
    +
    +
    +

    A co_yield expression can also produce a value, +which allows the user of yielding coroutine to push values into it.

    +
    +
    +
    +
    async::generator<int, bool> iota()
+{
+  int i = 0;
+  bool more = false;
+  do
+  {
+    more = co_yield i++;
+  }
+  while(more);
+  co_return -1;
+}
    +
    +
    +
    +
    +
    Stackless
    +
    +

    C++ coroutine are stack-less, which means they only allocate their own function frame.

    +
    +
    +

    See Stackless for more details.

    +
    +
    +
    +
    +
    +
    +
    +

    ← Previous: Async programming | ↑ Up: Coroutine Primer | ⌂ Home: Documentation boost.async | Next: Awaitables →

    +
    +
    + + + \ No newline at end of file diff --git a/delay.html b/delay.html new file mode 100644 index 00000000..ca0ffc83 --- /dev/null +++ b/delay.html @@ -0,0 +1,787 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    delay

    +
    +
    +

    Let’s start with the simplest example possible: a simple delay.

    +
    +
    +
    example/delay.cpp
    +
    +
    async::main co_main(int argc, char * argv[]) (1)
+{
+  asio::steady_timer tim{co_await asio::this_coro::executor, (2)
+                         std::chrono::milliseconds(std::stoi(argv[1]))}; (3)
+  co_await tim.async_wait(async::use_op); (4)
+  co_return 0; (5)
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + +
    1The co_main function defines an implicit main when defined +and is the easiest way to set up an environment to run asynchronous code.
    2Take the executor from the current coroutine promise.
    3Use an argument to set the timeout
    4Perform the wait by using async::use_op.
    5Return a value that gets returned from the implicit main.
    +
    +
    +

    In this example we use the async/main.hpp header, which provides us with a main coroutine if co_main +is defined as above. This has a few advantages:

    +
    +
    +
      +
    • +

      The environment get set up correctly (executor & memory)

      +
      • +
    • +

      asio is signaled that the context is single threaded

      +
      • +
    • +

      an asio::signal_set with SIGINT & SIGTERM is automatically connected to cancellations (i.e. Ctrl+C causes cancellations)

      +
      • +
    +
    +
    +

    This coroutine then has an executor in its promise (the promise the C++ name for a coroutine state. +Not to be confused with async/promise.hpp) which we can obtain through the dummy-awaitables in +the this_coro namespace.

    +
    +
    +

    We can then construct a timer and initiate the async_wait with use_op. +async provides multiple ways to co_await to interact with asio, of which use_op is the easiest.

    +
    +
    +
    +
    +

    ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: echo server →

    +
    +
    + + + \ No newline at end of file diff --git a/delay_op.html b/delay_op.html new file mode 100644 index 00000000..8c6f6b91 --- /dev/null +++ b/delay_op.html @@ -0,0 +1,783 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    delay op

    +
    +
    +

    We’ve used the use_op so far, to use an implicit operation based on asio’s completion token mechanic.

    +
    +
    +

    We can however implement our own ops, that can also utilize the async_ready optimization. +To leverage this coroutine feature, async provides an easy way to create a skipable operation:

    +
    +
    +
    example/delay_op.cpp
    +
    +
    struct wait_op final : async::op<system::error_code> (1)
+{
+  asio::steady_timer & tim;
+  wait_op(asio::steady_timer & tim) : tim(tim) {}
+  void ready(async::handler<system::error_code> h ) override (2)
+  {
+    if (tim.expiry() < std::chrono::steady_clock::now())
+      h(system::error_code{});
+  }
+  void initiate(async::completion_handler<system::error_code> complete) override (3)
+  {
+    tim.async_wait(std::move(complete));
+  }
+};
+
+
+async::main co_main(int argc, char * argv[])
+{
+  asio::steady_timer tim{co_await asio::this_coro::executor,
+                         std::chrono::milliseconds(std::stoi(argv[1]))};
+  co_await wait_op(tim); (4)
+  co_return 0; //
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + +
    1Declare the op. We inherit op to make it awaitable.
    2The pre-suspend check is implemented here
    3Do the wait if we need to
    4Use the op just like any other awaitable.
    +
    +
    +

    This way we can minimize the amounts of coroutine suspensions.

    +
    +
    +

    While the above is used with asio, you can also use these handlers +with any other callback based code.

    +
    +
    +
    +
    +

    ← Previous: price ticker | ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: Generator with push value →

    +
    +
    + + + \ No newline at end of file diff --git a/design.html b/design.html index 7c8c7970..3407cefd 100644 --- a/design.html +++ b/design.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -1153,7 +1155,7 @@

    Threading

    diff --git a/design:concepts.html b/design:concepts.html new file mode 100644 index 00000000..012426db --- /dev/null +++ b/design:concepts.html @@ -0,0 +1,785 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Concepts

    +
    +
    +

    This library has two fundamental concepts:

    +
    +
    + +
    +
    +

    An awaitable is an expression that can be used with co_await +from within a coroutine, e.g.:

    +
    +
    +
    +
    co_await delay(50ms);
    +
    +
    +
    +

    An actual awaitable is a type that can be co_await-ed from within any coroutine, +like a delay operation. +A pseudo-awaitable is one that can only be used in coroutines adding special +functionality for it. It is akin to a contextual pseudo-keyword.

    +
    +
    +

    All the verbs in the this_coro namespace are such pseudo-awaitables.

    +
    +
    +
    +
    auto exec = co_await this_coro::executor;
    +
    +
    +
    + + + + + +
    + + +This library exposes a set of enable_* base classes for promises, +to make the creation of custom coroutines easy. +
    +
    +
    +

    A coroutine in the context of this documentation refers +to an asynchronous coroutine, i.e. synchronous coroutines like +generator +are not considered.

    +
    +
    +

    All coroutines except main are also actual awaitables.

    +
    +
    +
    +
    +

    ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Executors →

    +
    +
    + + + \ No newline at end of file diff --git a/design:interrupt_await.html b/design:interrupt_await.html new file mode 100644 index 00000000..e4f87988 --- /dev/null +++ b/design:interrupt_await.html @@ -0,0 +1,782 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    interrupt_await

    +
    +
    +

    If it naively cancelled it would however lose data. +Thus, the concept of interrupt_await is introduced, +which tells the awaitable (that supports it) +to immediately resume the awaiter and return or throw an ignored value.

    +
    +
    +
    Example of an interruptible awaitable
    +
    +
    struct awaitable
+{
+   bool await_ready() const;
+
+   template<typename Promise>
+   std::coroutine_handle<void> await_suspend(std::coroutine_handle<Promise> h);
+
+   T await_resume();
+
+   void interrupt_await() &;
+};
    +
    +
    +
    +

    If the interrupt_await doesn’t result in immediate resumption (of h), +select will send a cancel signal.

    +
    +
    +

    select applies these with the correct reference qualification:

    +
    +
    +
    +
    auto g = gen1();
+select(g, gen2());
    +
    +
    +
    +

    The above will call a interrupt_await() & function for g1 and interrupt_await() && for g2 if available.

    +
    +
    + + + + + +
    + + +Generally speaking, the coroutines in async support lvalue interruption, ie. interrupt_await() &. +channel operations are unqualified, i.e. work in both cases. +
    +
    +
    +

    join and gather will forward interruptions, +i.e. this will only interrupt g1 and g2 if gen2() completes first:

    +
    +
    +
    +
    +

    ← Previous: Select | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Associators →

    +
    +
    + + + \ No newline at end of file diff --git a/design:promise.html b/design:promise.html new file mode 100644 index 00000000..f677bbce --- /dev/null +++ b/design:promise.html @@ -0,0 +1,744 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Promise

    +
    +
    +

    The main coroutine type is a promise, which is eager. +The reason to default to this, is that the compiler can optimize out +promises that do not suspend, like this:

    +
    +
    +
    +
    async::promise<void> noop()
+{
+  co_return;
+}
    +
    +
    +
    +

    Awaiting the above operation is in theory a noop, +but practically speaking, compilers aren’t there as of 2023.

    +
    +
    +
    +
    +

    ← Previous: cancellation | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Select →

    +
    +
    + + + \ No newline at end of file diff --git a/design:select.html b/design:select.html new file mode 100644 index 00000000..0accc5d1 --- /dev/null +++ b/design:select.html @@ -0,0 +1,779 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Select

    +
    +
    +

    The most important synchronization mechanism is the select function.

    +
    +
    +

    It awaits multiple awaitables in a pseudo-random order +and will return the result of the first one completion, before disregarding the rest.

    +
    +
    +

    That is, it initiates the co_await in a pseudo-random order and stops once one +awaitable is found to be ready or completed immediately.

    +
    +
    +
    +
    async::generator<int> gen1();
+async::generator<double> gen2();
+
+async::promise<void> p()
+{
+  auto g1 = gen1();
+  auto g2 = gen2();
+  while (!co_await async::this_coro::cancelled)
+  {
+    switch(auto v = co_await select(g1, g2); v.index())
+    {
+    case 0:
+      printf("Got int %d\n", get<0>(v));
+      break;
+    case 1:
+      printf("Got double %f\n", get<1>(v));
+      break;
+    }
+  }
+}
    +
    +
    +
    +

    The select must however internally wait for all awaitable to complete +once it initiates to co_await. +Therefor, once the first awaitable completes, +it tries to interrupt the rest, and if that fails cancels them.

    +
    +
    +

    select is the preferred way to trigger cancellations, e.g:

    +
    +
    +
    +
    async::promise<void> timeout();
+async::promise<void> work();
+
+select(timeout(), work());
    +
    +
    +
    +
    +
    +

    ← Previous: Promise | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: interrupt_await →

    +
    +
    + + + \ No newline at end of file diff --git a/detached.html b/detached.html new file mode 100644 index 00000000..a987a9fc --- /dev/null +++ b/detached.html @@ -0,0 +1,897 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/detached.hpp

    +
    +
    +

    A detached is an eager coroutine that can co_await but not co_return values. +That is, it cannot be resumed and is usually not awaited.

    +
    +
    +
    +
    async::detached delayed_print(std::chrono::milliseconds ms)
+{
+  asio::steady_timer tim{co_await async::this_coro::executor, ms};
+  co_await tim.async_wait(async::use_op);
+  printf("Hello world\n");
+}
+
+async::main co_main(int argc, char *argv[])
+{
+  delayed_print();
+  co_return 0;
+}
    +
    +
    +
    +

    Promises are mainly used to spawn tasks easily.

    +
    +
    +
    +
    async::detached my_task();
+
+async::main co_main(int argc, char *argv[])
+{
+  my_task(); (1)
+  co_await delay(std::chrono::milliseconds(50));
+  co_return 0;
+}
    +
    +
    +
    + + + + + +
    1Spawn off the detached coro.
    +
    +
    +

    A detached can assign itself a new cancellation source like this:

    +
    +
    +
    +
    async::detached my_task(asio::cancellation_slot sl)
+{
+   co_await this_coro::reset_cancellation_source(sl);
+   // do somework
+}
+
+async::main co_main(int argc, char *argv[])
+{
+  asio::cancellation_signal sig;
+  my_task(sig.slot()); (1)
+  co_await delay(std::chrono::milliseconds(50));
+  sig.emit(asio::cancellation_type::all);
+  co_return 0;
+}
    +
    +
    +
    +

    Executor

    +
    +

    The executor is taken from the thread_local get_executor function, unless a asio::executor_arg is used +in any position followed by the executor argument.

    +
    +
    +
    +
    async::detached my_gen(asio::executor_arg_t, asio::io_context::executor_type exec_to_use);
    +
    +
    +
    +
    +

    Memory Resource

    +
    +

    The memory resource is taken from the thread_local get_default_resource function, +unless a std::allocator_arg is used in any position followed by a polymorphic_allocator argument.

    +
    +
    +
    +
    async::detached my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<void> alloc);
    +
    +
    +
    +
    +

    Outline

    +
    +
    +
    struct detached {};
    +
    +
    +
    + + + + + +
    1Supports Interrupt Wait
    +
    +
    +
    +

    Promise

    +
    +

    The thread detached has the following properties.

    +
    +
    + +
    +
    +
    +
    +
    +

    ← Previous: async/task.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/op.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/echo_server.html b/echo_server.html new file mode 100644 index 00000000..c221b642 --- /dev/null +++ b/echo_server.html @@ -0,0 +1,898 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    echo server

    +
    +
    +

    We’ll be using the use_op (asio completion) token everywhere, +so we’re using a default completion token, so that we can skip the last parameters.

    +
    +
    +
    example/echo_server.cpp declarations
    +
    +
    namespace async = boost::async;
+using boost::asio::ip::tcp;
+using boost::asio::detached;
+using tcp_acceptor = async::use_op_t::as_default_on_t<tcp::acceptor>;
+using tcp_socket   = async::use_op_t::as_default_on_t<tcp::socket>;
+namespace this_coro = boost::async::this_coro;
    +
    +
    +
    +

    We’re writing the echo function as a promise coroutine. +It’s an eager coroutine and recommended as the default; +in case a lazy coro is needed, task is available.

    +
    +
    +
    example/echo_server.cpp echo function
    +
    +
    async::promise<void> echo(tcp_socket socket)
+{
+  try (1)
+  {
+    char data[4096];
+    while (socket.is_open()) (2)
+    {
+      std::size_t n = co_await socket.async_read_some(boost::asio::buffer(data)); (3)
+      co_await async_write(socket, boost::asio::buffer(data, n)); (4)
+    }
+  }
+  catch (std::exception& e)
+  {
+    std::printf("echo: exception: %s\n", e.what());
+  }
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + +
    1When using the use_op completion token, I/O errors are translated into C++ exceptions. Additionally, +if the coroutine gets cancelled (e.g. because the user hit Ctrl-C), +an exception will be raised, too. Under these conditions, we print the error and exit the loop.
    2We run the loop until we get cancelled (exception) or the user closes the connection.
    3Read as much as is available.
    4Write all the read bytes.
    +
    +
    +

    Note that promise is eager. Calling echo will immediately execute code until async_read_some +and then return control to the caller.

    +
    +
    +

    Next, we also need an acceptor function. Here, we’re using a generator to manage the acceptor state. +This is a coroutine that can be co_awaited multiple times, until a co_return expression is reached.

    +
    +
    +
    example/echo_server.cpp listen function
    +
    +
    async::generator<tcp_socket> listen()
+{
+  tcp_acceptor acceptor({co_await async::this_coro::executor}, {tcp::v4(), 55555});
+  for (;;) (1)
+  {
+    tcp_socket sock = co_await acceptor.async_accept(); (2)
+    co_yield std::move(sock); (3)
+  }
+  co_return tcp_socket{acceptor.get_executor()}; (4)
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + +
    1Cancellation will also lead to an exception here being thrown from the co_await
    2Asynchronously accept the connection
    3Yield it to the awaiting coroutine
    4co_return a value for C++ conformance.
    +
    +
    +

    With those two functions we can now write the server:

    +
    +
    +
    example/echo_server.cpp run_server function
    +
    +
    async::promise<void> run_server(async::wait_group & workers)
+{
+  auto l = listen(); (1)
+  while (true)
+  {
+    if (workers.size() == 10u)
+      co_await workers.wait_one();  (2)
+    else
+      workers.push_back(echo(co_await l)); (3)
+  }
+}
    +
    +
    +
    + + + + + + + + + + + + + +
    1Construct the listener generator coroutine. When the object is destroyed, +the coroutine will be cancelled, performing all required cleanup.
    2When we have more than 10 workers, we wait for one to finish
    3Accept a new connection & launch it.
    +
    +
    +

    The wait_group is used to manage the running echo functions. +This class will cancel & await the running echo coroutines.

    +
    +
    +

    We do not need to do the same for the listener, because it will just stop on its own, when l gets destroyed. +The destructor of a generator will cancel it.

    +
    +
    +

    Since the promise is eager, just calling it is enough to launch. +We then put those promises into a wait_group which will allow us to tear down all the workers on scope exit.

    +
    +
    +
    example/echo_server.cpp co_main function
    +
    +
    async::main co_main(int argc, char ** argv)
+{
+  co_await async::with(async::wait_group(), &run_server); (1)
+  co_return 0u;
+}
    +
    +
    +
    + + + + + +
    1Run run_server with an async scope.
    +
    +
    +

    The with function shown above, will run a function with a resource such as wait_group. +On scope exit with will invoke & co_await an asynchronous teardown function. +This will cause all connections to be properly shutdown before co_main exists.

    +
    +
    +
    +
    +

    ← Previous: delay | ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: price ticker →

    +
    +
    + + + \ No newline at end of file diff --git a/error.html b/error.html new file mode 100644 index 00000000..1fa17f13 --- /dev/null +++ b/error.html @@ -0,0 +1,775 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/error.hpp

    +
    +
    +

    In order to make errors easier to manage, async provides an error_category to be used with +boost::system::error_code.

    +
    +
    +
    +
    enum class error
+{
+  moved_from,
+  detached,
+  completed_unexpected,
+  wait_not_ready,
+  already_awaited,
+  allocation_failed
+};
+
+system::error_category & async_category();
+system::error_code make_error_code(error e);
    +
    +
    +
    +
    +
    +

    ← Previous: async/async_for.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/config.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/event-loops.html b/event-loops.html new file mode 100644 index 00000000..8d4d433f --- /dev/null +++ b/event-loops.html @@ -0,0 +1,513 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    Event Loops

    +
    +
    +

    Since the coroutines in async can co_await events, they need to be run on an event-loop. +That is another piece of code is responsible for tracking outstanding event and resume a resuming coroutines that are awaiting them. +This pattern is very common and is used in a similar way by node.js or python’s asyncio.

    +
    +
    +

    async uses an asio::io_context as its default event loop.

    +
    +
    +

    The event loop is accessed through an executor (following the asio terminology) and can be manually set using set_executor.

    +
    +
    +
    +
    +

    ← Previous: Awaitables | ↑ Up: Coroutine Primer | ⌂ Home: Documentation boost.async | Next: Tutorial →

    +
    +
    + + + \ No newline at end of file diff --git a/executors.html b/executors.html new file mode 100644 index 00000000..91c8e239 --- /dev/null +++ b/executors.html @@ -0,0 +1,797 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Executors

    +
    +
    +

    Since everything is asynchronous the library needs to use an event-loop. +Because everything is single-threaded, it can be assumed that there is exactly one executor +per thread, which will suffice for 97% of use-cases. +Therefore, there is a thread_local executor that gets used as default +by the coroutine objects (although stored by copy in the coroutine promise).

    +
    +
    +

    Likewise, there is one executor type used by the library, +which defaults to asio::any_io_executor.

    +
    +
    + + + + + +
    + + +If you write your own coroutine, it should hold a copy of the executor, +and have a get_executor function returning it by const reference. +
    +
    +
    +

    Using Strands

    +
    +

    While strands can be used, they are not compatible with the thread_local executor. +This is because they might switch threads, thus they can’t be thread_local.

    +
    +
    +

    If you wish to use strands (e.g. through a spawn) +the executor for any promise, generator or channel +must be assigned manually.

    +
    +
    +

    In the case of a channel this is a constructor argument, +but for the other coroutine types, asio::executor_arg needs to be used. +This is done by having asio::executor_arg_t (somewhere) in the argument +list directly followed by the executor to be used in the argument list of the coroutine, e.g.:

    +
    +
    +
    +
    async::promise<void> example_with_executor(int some_arg, asio::executor_arg_t, async::executor);
    +
    +
    +
    +

    This way the coroutine-promise can pick up the executor from the third argument, +instead of defaulting to the thread_local one.

    +
    +
    +

    The arguments can of course be defaulted, to make them less inconvenient, +if they are sometimes with a thread_local executor.

    +
    +
    +
    +
    async::promise<void> example_with_executor(int some_arg,
+                                           asio::executor_arg_t = asio::executor_arg,
+                                           async::executor = async::this_thread::get_executor());
    +
    +
    +
    +

    If this gets omitted on a strand an exception of type asio::bad_allocator is thrown, +or - worse - the wrong executor is used.

    +
    +
    +
    +
    +
    +

    ← Previous: Concepts | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: polymorphic memory resource →

    +
    +
    + + + \ No newline at end of file diff --git a/gather.html b/gather.html new file mode 100644 index 00000000..ff0dfe7b --- /dev/null +++ b/gather.html @@ -0,0 +1,831 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/gather.hpp

    +
    +
    +

    The gather function can be used to co_await multiple awaitables +at once with cancellations being passed through.

    +
    +
    +

    The function will gather all completion and return them as system::result, +i.e. capture conceptions as values. One awaitable throwing an exception will not cancel the others.

    +
    +
    +

    It can be called as a variadic function with multiple Awaitable or as on a range of awaitables.

    +
    +
    +
    +
    async::promise<void> task1();
+async::promise<void> task2();
+
+async::promise<void> do_gather()
+{
+  co_await async::gather(task1(), task2()); (1)
+  std::vector<async::promise<void>> aws {task1(), task2()};
+  co_await async::gather(aws); (2)
+}
    +
    +
    +
    + + + + + + + + + +
    1Wait for a variadic set of awaitables
    2Wait for a vector of awaitables
    +
    +
    +

    The gather will invoke the functions of the awaitable as if used in a co_await expression.

    +
    +
    +
    Signatures of join
    +
    +
    extern promise<void> pv1, pv2;
+std::tuple<system::result<int>, system::result<int>> r1 = co_await gather(pv1, pv2);
+
+std::vector<promise<void>> pvv;
+pmr::vector<system::result<void>> r2 =  co_await gather(pvv);
+
+extern promise<int> pi1, pi2;
+std::tuple<system::result<monostate>,
+           system::result<monostate>,
+           system::result<int>,
+           system::result<int>> r3 = co_await gather(pv1, pv2, pi1, pi2);
+
+std::vector<promise<int>> piv;
+pmr::vector<system::result<int>> r4 = co_await gather(piv);
    +
    +
    +
    +

    Outline

    +
    +
    +
    // Variadic gather
+template<asio::cancellation_type Ct = asio::cancellation_type::all, awaitable... Promise>
+awaitable gather(Promise && ... p);
+
+// Ranged gather
+template<asio::cancellation_type Ct = asio::cancellation_type::all, range<awaitable>>
+awaitable gather(PromiseRange && p);
    +
    +
    +
    +
    +
    +
    +

    ← Previous: async/select.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/join.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/generator.html b/generator.html new file mode 100644 index 00000000..b51ef73a --- /dev/null +++ b/generator.html @@ -0,0 +1,1010 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/generator.hpp

    +
    +
    +

    A generator is an eager coroutine that can co_await and co_yield values to the caller.

    +
    +
    +
    +
    async::generator<int> example()
+{
+  printf("In coro 1\n");
+  co_yield 2;
+  printf("In coro 3\n");
+  co_return 4;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+  printf("In main 0\n");
+  auto f = example(); // call and let it run until the first co_yield
+  printf("In main 1\n");
+  printf("In main %d\n", co_await f);
+  printf("In main %d\n", co_await f);
+  return 0;
+}
    +
    +
    +
    +

    Which will generate the following output

    +
    +
    +
    +
    In main 0
+In coro 1
+In main 1
+In main 2
+In coro 3
+In main 4
    +
    +
    +
    +
    +Diagram +
    +
    +
    +

    Values can be pushed into the generator, when Push (the second template parameter) is set to non-void:

    +
    +
    +
    +
    async::generator<int, int> example()
+{
+  printf("In coro 1\n");
+  int i =  co_yield 2;
+  printf("In coro %d\n");
+  co_return 4;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+  printf("In main 0\n");
+  auto f = example(); // call and let it run until the first co_yield
+  printf("In main %d\n", co_await f(3)); (1)
+  return 0;
+}
    +
    +
    +
    + + + + + +
    1The pushed value gets passed through operator() to the result of co_yield.
    +
    +
    +

    Which will generate the following output

    +
    +
    +
    +
    In main 0
+In coro 1
+In main 2
+Pushed 2
+In coro 3
+In main 4
    +
    +
    +
    +

    Lazy

    +
    +

    A generator can be turned lazy by awaiting initial. +This co_await expression will produce the Push value. +This means the generator will wait until it’s awaited for the first time, +and then process the newly pushed value and resume at the next co_yield.

    +
    +
    +
    +
    async::generator<int, int> example()
+{
+  int v = co_await async::this_coro::initial;
+  printf("In coro %d\n", v);
+  co_yield 2;
+  printf("In coro %d\n", v);
+  co_return 4;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+  printf("In main 0\n");
+  auto f = example(); // call and let it run until the first co_yield
+  printf("In main 1\n"); // < this is now before the co_await initial
+  printf("In main %d\n", co_await f(1));
+  printf("In main %d\n", co_await f(3));
+  return 0;
+}
    +
    +
    +
    +

    Which will generate the following output

    +
    +
    +
    +
    In main 0
+In main 1
+In coro 1
+In main 2
+In coro 3
+In main 4
    +
    +
    +
    +
    +Diagram +
    +
    +
    +
    +

    Executor

    +
    +

    The executor is taken from the thread_local get_executor function, unless a asio::executor_arg is used +in any position followed by the executor argument.

    +
    +
    +
    +
    async::generator<int> my_gen(asio::executor_arg_t, asio::io_context::executor_type exec_to_use);
    +
    +
    +
    +
    +

    Memory Resource

    +
    +

    The memory resource is taken from the thread_local get_default_resource function, +unless a std::allocator_arg is used in any position followed by a polymorphic_allocator argument.

    +
    +
    +
    +
    async::generator<int> my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<void> alloc);
    +
    +
    +
    +
    +

    Outline

    +
    +
    +
    template<typename Yield, typename Push = void>
+struct [[nodiscard]] generator
+{
+  // Movable
+
+  generator(generator &&lhs) noexcept = default;
+  generator& operator=(generator &&) noexcept = default;
+
+  // True until it co_returns & is co_awaited after (1)
+  explicit operator bool() const;
+
+  // Cancel the generator. (3)
+  void cancel(asio::cancellation_type ct = asio::cancellation_type::all);
+
+  // Check if a value is available
+  bool ready() const;
+
+  // Get the return value. Throws if not ready.
+  Yield get();
+
+  // Cancel & detach the generator.
+  ~generator();
+
+  // an awaitable that results in value of Yield.
+  using generator_awaitable = unspecified;
+
+  // Present when Push != void
+  generator_awaitable operator()(      Push && push);
+  generator_awaitable operator()(const Push &  push);
+
+  // Present when Push == void, i.e. can co_await the generator directly.
+  generator_awaitable operator co_await (); (2)
+
+};
    +
    +
    +
    + + + + + + + + + + + + + +
    1This allows code like while (gen) co_await gen:
    2Supports Interrupt Wait
    3A cancelled generator maybe be resumable
    +
    +
    +
    +

    Promise

    +
    +

    The generator promise has the following properties.

    +
    +
    + +
    +
    +
    +
    +
    +

    ← Previous: async/promise.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/task.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/generator_with_push_value.html b/generator_with_push_value.html new file mode 100644 index 00000000..cd4ace20 --- /dev/null +++ b/generator_with_push_value.html @@ -0,0 +1,797 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Generator with push value

    +
    +
    +

    Coroutines with push values are not as common, +but can simplify certain issues significantly.

    +
    +
    +

    Since we’ve already got a json_reader in the previous example, +here’s how we can write a json_writer that gets values pushed in.

    +
    +
    +

    The advantage of using a generator is the internal state management.

    +
    +
    +
    +
    async::generator<system::error_code, json::object>
+    json_writer(websocket_type & ws)
+try
+{
+    char buffer[4096];
+    json::serializer ser;
+
+    while (ws.is_open()) (1)
+    {
+        auto val = co_yield system::error_code{}; (2)
+
+        while (!ser.done())
+        {
+            auto sv = ser.read(buffer);
+            co_await ws.async_write({sv.data(), sv.size()}); (3)
+        }
+
+    }
+    co_return {};
+}
+catch (system::system_error& e)
+{
+    co_return e.code();
+}
+catch (std::exception & e)
+{
+    std::cerr << "Error reading: " << e.what() << std::endl;
+    throw;
+}
    +
    +
    +
    + + + + + + + + + + + + + +
    1Keep running as long as the socket is open
    2co_yield the current error and retrieve a new value.
    3Write a frame to the websocket
    +
    +
    +

    Now we can use the generator like this:

    +
    +
    +
    +
    auto g = json_writer(my_ws);
+
+extern std::vector<json::value> to_write;
+
+for (auto && tw : std::move(to_write))
+{
+    if (auto ec = co_await g(std::move(tw)))
+        return ec; // yield error
+}
    +
    +
    +
    +
    +
    +

    ← Previous: delay op | ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: Advanced examples →

    +
    +
    + + + \ No newline at end of file diff --git a/immediate.html b/immediate.html new file mode 100644 index 00000000..c1ae8dde --- /dev/null +++ b/immediate.html @@ -0,0 +1,766 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Immediate

    +
    +
    +

    This benchmark utilizes the immediate completion, by using a channel +with a size of 1, so that every operation is immediate.

    +
    +
    +
    +
    async::task<void> atest()
+{
+  asio::experimental::channel<void(system::error_code)> chan{co_await async::this_coro::executor, 1u};
+  for (std::size_t i = 0u; i < n; i++)
+  {
+    co_await chan.async_send(system::error_code{}, async::use_op);
+    co_await chan.async_receive(async::use_op);
+  }
+}
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 7. result for 10M times in ms
    gcc 12clang 16

    async

    1810

    1864

    awaitable

    3109

    4110

    stackful

    3922

    4705

    +
    +
    +
    +

    ← Previous: Running noop coroutine in parallel | ↑ Up: Benchmarks | ⌂ Home: Documentation boost.async | Next: Channels →

    +
    +
    + + + \ No newline at end of file diff --git a/index.html b/index.html index 851121cb..ef398e46 100644 --- a/index.html +++ b/index.html @@ -457,6 +457,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -487,6 +489,9 @@

    Documentation boost.async

    Coroutine Primer

  • +

    Tour

    +
    • +

  • Tutorial

  • @@ -516,7 +521,7 @@

    Documentation boost.async

    diff --git a/join.html b/join.html new file mode 100644 index 00000000..7c2065b2 --- /dev/null +++ b/join.html @@ -0,0 +1,852 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/join.hpp

    +
    +
    +

    The join function can be used to co_await multiple awaitable at once with properly connected cancellations.

    +
    +
    +

    The function will gather all completion and return them as values, unless an exception is thrown. +If an exception is thrown, all outstanding ops are cancelled (or detached if possible) +and the first exception gets rethrown.

    +
    +
    + + + + + +
    + + +void will be returned as variant2::monostate in the tuple, unless all awaitables yield void. +
    +
    +
    +

    It can be called as a variadic function with multiple Awaitable or as on a range of awaitables.

    +
    +
    +
    +
    async::promise<void> task1();
+async::promise<void> task2();
+
+async::promise<void> do_join()
+{
+  co_await async::join(task1(), task2()); (1)
+  std::vector<async::promise<void>> aws {task1(), task2()};
+  co_await async::join(aws); (2)
+}
    +
    +
    +
    + + + + + + + + + +
    1Wait for a variadic set of awaitables
    2Wait for a vector of awaitables
    +
    +
    +

    The join will invoke the functions of the awaitable as if used in a co_await expression.

    +
    +
    +
    Signatures of join
    +
    +
    extern promise<void> pv1, pv2;
+/* void */ co_await join(pv1, pv2);
+
+std::vector<promise<void>> pvv;
+/* void */ co_await join(pvv);
+
+extern promise<int> pi1, pi2;
+std::tuple<monostate, monostate, int, int> r1 = co_await join(pv1, pv2, pi1, pi2);
+
+std::vector<promise<int>> piv;
+pmr::vector<int> r2 = co_await join(piv);
    +
    +
    +
    +

    Outline

    +
    +
    +
    // Variadic join
+template<asio::cancellation_type Ct = asio::cancellation_type::all, awaitable... Promise>
+awaitable join(Promise && ... p);
+
+// Ranged join
+template<asio::cancellation_type Ct = asio::cancellation_type::all, range<awaitable>>
+awaitable join(PromiseRange && p);
    +
    +
    +
    + + + + + +
    + + +Selecting an on empty range will cause an exception. +
    +
    +
    +
    +
    +
    +

    ← Previous: async/gather.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/wait_group.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/lazy_eager.html b/lazy_eager.html new file mode 100644 index 00000000..b51931a9 --- /dev/null +++ b/lazy_eager.html @@ -0,0 +1,796 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Lazy & eager

    +
    +
    +

    Coroutines are lazy if they only start execution of its code after it gets resumed, while an eager one will execute right-away until its first suspension point (i.e. a co_await, co_yield or co_return expression.)

    +
    +
    +
    +
    lazy_coro co_example()
+{
+    printf("Entered coro\n");
+    co_yield 0;
+    printf("Coro done\n");
+}
+
+int main()
+{
+    printf("enter main\n");
+    auto lazy = co_example();
+    printf("constructed coro\n");
+    lazy.resume();
+    printf("resumed once\n");
+    lazy.resume();
+    printf("resumed twice\n");
+    return 0;
+}
    +
    +
    +
    +

    Which will produce output like this:

    +
    +
    +
    +
    enter main
+constructed coro
+Entered coro
+resumed once
+Coro Done
+resumed twice
    +
    +
    +
    +
    +Diagram +
    +
    +
    +

    Whereas an eager coro would look like this:

    +
    +
    +
    +
    eager_coro co_example()
+{
+    printf("Entered coro\n");
+    co_yield 0;
+    printf("Coro done\n");
+}
+
+int main()
+{
+    printf("enter main\n");
+    auto lazy = co_example();
+    printf("constructed coro\n");
+    lazy.resume();
+    printf("resumed once\n");
+    return 0;
+}
    +
    +
    +
    +

    Which will produce output like this:

    +
    +
    +
    +
    enter main
+Entered coro
+constructed coro
+resume once
+Coro Done
    +
    +
    +
    +
    +Diagram +
    +
    +
    +
    +
    +

    ← Previous: Stackless | ↑ Up: Technical Background | ⌂ Home: Documentation boost.async | Next: Benchmarks →

    +
    +
    + + + \ No newline at end of file diff --git a/leaf.html b/leaf.html new file mode 100644 index 00000000..0c9e0155 --- /dev/null +++ b/leaf.html @@ -0,0 +1,788 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/leaf.hpp

    +
    +
    +

    Async provides integration with boost.leaf. +It provides functions similar to leaf that take an awaitables +instead of a function object and return an awaitable.

    +
    +
    +
    +
    template<awaitable TryAwaitable, typename ... H >
+auto try_catch(TryAwaitable && try_coro, H && ... h );
+
+template<awaitable TryAwaitable, typename ... H >
+auto try_handle_all(TryAwaitable && try_coro, H && ... h );
+
+template<awaitable TryAwaitable, typename ... H >
+auto try_handle_some(TryAwaitable && try_coro, H && ... h );
    +
    +
    +
    +

    See the leaf documentation for details.

    +
    +
    + +
    +
    +
    +
    +

    ← Previous: async/config.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: Technical Background →

    +
    +
    + + + \ No newline at end of file diff --git a/main.html b/main.html new file mode 100644 index 00000000..bbd06b33 --- /dev/null +++ b/main.html @@ -0,0 +1,885 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/main.hpp

    +
    +
    +

    The easiest way to get started with an async application is to use the co_main function with the following signature:

    +
    +
    +
    +
    async::main co_main(int argc, char *argv[]);
    +
    +
    +
    +

    Declaring co_main will add a main function that performs all the necessary steps to run a coroutine +on an event loop. +This allows us to write a very simple asynchronous programs;

    +
    +
    +
    +
    async::main co_main(int argc, char *argv[])
+{
+  auto exec = co_await async::this_coro::executor;             (1)
+  asio::steady_timer tim{exec, std::chrono::milliseconds(50)}; (2)
+  co_await tim.async_wait(async::use_op);                      (3)
+  co_return 0;
+}
    +
    +
    +
    + + + + + + + + + + + + + +
    1get the executor main running on
    2Use it with an asio object
    3co_await an async operation
    +
    +
    +

    The main promise will create an asio::signal_set and uses it for cancellation. +SIGINT becomes total , while SIGTERM becomes terminal cancellation.

    +
    +
    + + + + + +
    + + +The cancellation will not be forwarded to detached coroutines. +The user will need to take care to end then on cancellation, +since the program otherwise doesn’t allow graceful termination. +
    +
    +
    +

    Executor

    +
    +

    It will also create an asio::io_context to run on, which you can get through the this_coro::executor. +It will be assigned to the async::this_thread::get_executor() .

    +
    +
    +
    +

    Memory Resource

    +
    +

    It also creates a memory resource that will be used as a default for internal memory allocations. +It will be assigned to the thread_local to the async::this_thread::get_default_resoruce().

    +
    +
    +
    +

    Promise

    +
    +

    Every coroutine has an internal state, called promise (not to be confused with the async::promise). +Depending on the coroutine properties different things can be co_await-ed, like we used in the example above.

    +
    +
    +

    They are implemented through inheritance, and shared among different promise types

    +
    +
    +

    The main promise has the following properties.

    +
    +
    + +
    +
    +
    +

    Specification

    +
    +
      +
    1. +

      declaring co_main will implicitly declare a main function

      +
      2. +
    2. +

      main is only present when co_main is defined.

      +
      3. +
    3. +

      SIGINT and SIGTERM will cause cancellation of the internal task.

      +
      4. +
    +
    +
    +
    +
    +
    +

    ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/promise.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/motivation.html b/motivation.html index b2976790..8b5f8b75 100644 --- a/motivation.html +++ b/motivation.html @@ -457,6 +457,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -491,7 +493,8 @@

    Motivation

    This library is meant to provide this to C++: simple single threaded asynchronicity akin to node.js and asyncio in python that works with existing libraries like -boost.beast, boost.mysql or boost.redis.

    +boost.beast, boost.mysql or boost.redis. +It based on boost.asio.

    It takes a collection of concepts from other languages and provides them based on C++20 coroutines.

    @@ -537,7 +540,7 @@

    Motivation

    diff --git a/overview.html b/overview.html index 18a00332..d9d921cd 100644 --- a/overview.html +++ b/overview.html @@ -457,6 +457,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -548,6 +550,41 @@

    Overview

    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 4. Reading guide

    Coroutine Primer

    A short introduction to C++ coroutines

    Read if you’ve never used coroutines before

    Tour

    An abbreviated high level view of the features and concepts

    Read if you’re familiar with asio & coroutines and want a rough idea what this library offers.

    Tutorial

    Low level view of usages

    Read if you want to get coding quickly

    Reference

    API reference

    Look up details while coding

    Technical Background

    Some implementation details

    Read if you’re not confused enough

    @@ -557,7 +594,7 @@

    Overview

    diff --git a/polymorphic_memory_resource.html b/polymorphic_memory_resource.html new file mode 100644 index 00000000..83ee95bc --- /dev/null +++ b/polymorphic_memory_resource.html @@ -0,0 +1,545 @@ + + + + + + + + +Documentation boost.async + + + + + + + +
    +
    +

    polymorphic memory resource

    +
    +
    +

    Similarly, the library uses a thread_local pmr::memory_resource to allocate +coroutine frames & to use as allocator on asynchronous operations.

    +
    +
    +

    The reason is, that users may want to customize allocations, +e.g. to avoid locks, limit memory usage or monitor usage. +pmr allows us to achieve this without introducing unnecessary template parameters, +i.e. no promise<T, Allocator> complexity. +Using pmr however does introduce some minimal overheads, +so a user has the option to disable by defining BOOST_ASYNC_NO_PMR.

    +
    +
    +

    op uses an internal resource optimized for asio’s allocator usages +and gather, select and join use a monotonic resource to miminize allocations. +Both still work with BOOST_ASYNC_NO_PMR defined, in which case they’ll use new/delete as upstream allocations.

    +
    +
    +

    main and thread single pmr::unsynchronized_pool_resource per thread with PMR enabled.

    +
    +
    + + + + + +
    + + +If you write your own coroutine, it should have a get_allocator function +returning a pmr::polymorphic_allocator<void>. +
    +
    +
    +
    +
    +

    ← Previous: Executors | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: cancellation →

    +
    +
    + + + \ No newline at end of file diff --git a/posting_to_an_executor.html b/posting_to_an_executor.html new file mode 100644 index 00000000..77ff1490 --- /dev/null +++ b/posting_to_an_executor.html @@ -0,0 +1,762 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Posting to an executor

    +
    +
    +

    The benchmark is running the following code, with async’s task, asio::awaitable and `asio’s +stackful coroutine (boost.context) based.

    +
    +
    +
    +
    async::task<void> atest()
+{
+  for (std::size_t i = 0u; i < n; i++)
+    co_await asio::post(async::use_op);
+}
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 5. results for 50M times in ms
    gcc 12clang 16

    async

    2472

    2098

    awaitable

    2432

    2253

    stackful

    3655

    3725

    +
    +
    +
    +

    ↑ Up: Benchmarks | ⌂ Home: Documentation boost.async | Next: Running noop coroutine in parallel →

    +
    +
    + + + \ No newline at end of file diff --git a/price_ticker.html b/price_ticker.html new file mode 100644 index 00000000..87030187 --- /dev/null +++ b/price_ticker.html @@ -0,0 +1,1151 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    price ticker

    +
    +
    +

    To demonstrate channels and other tools, we need a certain complexity. +For that purpose our project is a price ticker, that connects to +https://blockchain.info. A user can then connection to localhost +to query a given currency pair, like this:

    +
    +
    +
    +
    wscat -c localhost:8080/btc/usd
    +
    +
    +
    +

    First we do the same declarations as echo-server.

    +
    +
    +
    example/ticker.cpp declarations
    +
    +
    using executor_type = async::use_op_t::executor_with_default<async::executor>;
+using socket_type   = typename asio::ip::tcp::socket::rebind_executor<executor_type>::other;
+using acceptor_type = typename asio::ip::tcp::acceptor::rebind_executor<executor_type>::other;
+using websocket_type = beast::websocket::stream<asio::ssl::stream<socket_type>>;
+namespace http = beast::http;
    +
    +
    +
    +

    The next step is to write a function to connect an ssl-stream, +to connect upstream:

    +
    +
    +
    example/ticker.cpp connect
    +
    +
    async::promise<asio::ssl::stream<socket_type>> connect(
+        std::string host, boost::asio::ssl::context & ctx)
+{
+    asio::ip::tcp::resolver res{async::this_thread::get_executor()};
+    auto ep = co_await res.async_resolve(host, "https", async::use_op); (1)
+
+    asio::ssl::stream<socket_type> sock{async::this_thread::get_executor(), ctx};
+    co_await sock.next_layer().async_connect(*ep.begin()); (2)
+    co_await sock.async_handshake(asio::ssl::stream_base::client); (3)
+
+    co_return sock; (4)
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + +
    1Lookup the host
    2Connect to the endpoint
    3Do the ssl handshake
    4Return the socket to the caller
    +
    +
    +

    Next, we’ll need a function to do the websocket upgrade +on an existing ssl-stream.

    +
    +
    +
    example/ticker.cpp connect_to_blockchain_info
    +
    +
    async::promise<void> connect_to_blockchain_info(websocket_type & ws)
+{
+ ws.set_option(beast::websocket::stream_base::decorator(
+     [](beast::websocket::request_type& req)
+     {
+       req.set(http::field::user_agent,
+               std::string(BOOST_BEAST_VERSION_STRING) + " async-ticker");
+       req.set(http::field::origin,
+               "https://exchange.blockchain.com"); (1)
+     }));
+
+ co_await ws.async_handshake("ws.blockchain.info", "/mercury-gateway/v1/ws"); (2)
+}
    +
    +
    +
    + + + + + + + + + +
    1blockchain.info requires this header to be set.
    2Perform the websocket handshake.
    +
    +
    +

    Once the websocket is connected, we want to continuously receive json messages, +for which a generator is a good choice.

    +
    +
    +
    example/ticker.cpp json_read
    +
    +
    async::generator<json::object> json_reader(websocket_type & ws)
+try
+{
+    beast::flat_buffer buf;
+    while (ws.is_open()) (1)
+    {
+        auto sz = co_await ws.async_read(buf); (2)
+        json::string_view data{static_cast<const char*>(buf.cdata().data()), sz};
+        auto obj = json::parse(data);
+        co_yield obj.as_object(); (3)
+        buf.consume(sz);
+    }
+    co_return {};
+}
+catch (std::exception & e)
+{
+  std::cerr << "Error reading: " << e.what() << std::endl;
+  throw;
+}
    +
    +
    +
    + + + + + + + + + + + + + +
    1Keep running as long as the socket is open
    2Read a frame from the websocket
    3Parse & co_yield it as an object.
    +
    +
    +

    This then needs to be connected to subscriber, for which we’ll utilize channels to pass raw json. +To make life-time management easy, the subscriber will hold a shared_ptr, and the producer a weak_ptr.

    +
    +
    +
    example/ticker.cpp subscription types
    +
    +
    using subscription = std::pair<std::string, std::weak_ptr<async::channel<json::object>>>;
+using subscription_channel = std::weak_ptr<async::channel<json::object>>;
+using subscription_map = boost::unordered_multimap<std::string, subscription_channel>;
    +
    +
    +
    +

    The main function running the blockchain connector, operates on two inputs: +data coming from the websocket and a channel to handle new subscriptions.

    +
    +
    +
    example/ticker.cpp run blockchain_info
    +
    +
    async::promise<void> run_blockchain_info(async::channel<subscription> & subc)
+try
+{
+    asio::ssl::context ctx{asio::ssl::context_base::tls_client};
+    websocket_type ws{co_await connect("blockchain.info", ctx)};
+    co_await connect_to_blockchain_info(ws); (1)
+
+    subscription_map subs;
+    std::list<std::string> unconfirmed;
+
+    auto rd = json_reader(ws); (2)
+    while (ws.is_open()) (3)
+    {
+      switch (auto msg = co_await async::select(rd, subc.read()); msg.index()) (4)
+      {
+        case 0: (5)
+          if (auto ms = get<0>(msg);
+              ms.at("event") == "rejected") // invalid sub, cancel however subbed
+            co_await handle_rejections(unconfirmed, subs, ms);
+          else
+            co_await handle_update(unconfirmed, subs, ms, ws);
+        break;
+        case 1: // (6)
+            co_await handle_new_subscription(
+                unconfirmed, subs,
+                std::move(get<1>(msg)), ws);
+        break;
+      }
+    }
+
+    for (auto & [k ,c] : subs)
+    {
+        if (auto ptr = c.lock())
+            ptr->close();
+    }
+}
+catch(std::exception & e)
+{
+  std::cerr << "Exception: " << e.what() << std::endl;
+  throw;
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    1Initialize the connection
    2Instantiate the json_reader
    3Run as long as the websocket is open
    4Select, i.e. wait for either a new json message or subscription
    5When its a json handle an update or a rejection
    6Handle new subscription messages
    +
    +
    +

    The handle_* function’s contents are not as important for the async functionality, +so its skipped in this tutorial.

    +
    +
    +

    The handle_new_subscription function sends a message to the blockchain.info, +which will send a confirmation or rejection back. +The handle_rejection and handle_update will take the json values +and forward them to the subscription channel.

    +
    +
    +

    On the consumer side, our server will just forward data to the client. +If the client inputs data, we’ll close the websocket immediately. +We’re using as_tuple to ignore potential errors.

    +
    +
    +
    example/ticker.cpp read and close
    +
    +
    async::promise<void> read_and_close(beast::websocket::stream<socket_type> & st, beast::flat_buffer buf)
+{
+    system::error_code ec;
+    co_await st.async_read(buf, asio::as_tuple(async::use_op));
+    co_await st.async_close(beast::websocket::close_code::going_away, asio::as_tuple(async::use_op));
+    st.next_layer().close(ec);
+}
    +
    +
    +
    +

    Next, we’re running the session that the users sends

    +
    +
    +
    example/ticker.cpp run_session
    +
    +
    async::promise<void> run_session(beast::websocket::stream<socket_type> st,
+                                 async::channel<subscription> & subc)
+try
+{
+    http::request<http::empty_body> req;
+    beast::flat_buffer buf;
+    co_await http::async_read(st.next_layer(), buf, req); (1)
+    // check the target
+    auto r = urls::parse_uri_reference(req.target());
+    if (r.has_error() || (r->segments().size() != 2u)) (2)
+    {
+        http::response<http::string_body> res{http::status::bad_request, 11};
+        res.body() = r.has_error() ? r.error().message() :
+                    "url needs two segments, e.g. /btc/usd";
+        co_await http::async_write(st.next_layer(), res);
+        st.next_layer().close();
+        co_return ;
+    }
+
+    co_await st.async_accept(req); (3)
+
+    auto sym = std::string(r->segments().front()) + "-" +
+               std::string(r->segments().back());
+    boost::algorithm::to_upper(sym);
+    // close when data gets sent
+    auto p = read_and_close(st, std::move(buf)); (4)
+
+    auto ptr = std::make_shared<async::channel<json::object>>(1u); (5)
+    co_await subc.write(subscription{sym, ptr}); (6)
+
+    while (ptr->is_open() && st.is_open()) (7)
+    {
+      auto bb = json::serialize(co_await ptr->read());
+      co_await st.async_write(asio::buffer(bb));
+    }
+
+    co_await st.async_close(beast::websocket::close_code::going_away,
+                            asio::as_tuple(async::use_op)); (8)
+    st.next_layer().close();
+    co_await p; (9)
+
+}
+catch(std::exception & e)
+{
+    std::cerr << "Session ended with exception: " << e.what() << std::endl;
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    1Read the http request, because we want the path
    2Check the path, e.g. /btc/usd.
    3Accept the websocket
    4Start reading & close if the consumer sends something
    5Create the channel to receive updates
    6Send a subscription requests to run_blockchain_info
    7While the channel & websocket are open, we’re forwarding data.
    8Close the socket & ignore the error
    9Since the websocket is surely closed by now, wait for the read_and_close to close.
    +
    +
    +

    With run_session and run_blockchain_info written, we can not move on to main:

    +
    +
    +
    example/ticker.cpp main
    +
    +
    async::main co_main(int argc, char * argv[])
+{
+    acceptor_type acc{co_await async::this_coro::executor,
+                      asio::ip::tcp::endpoint (asio::ip::tcp::v4(), 8080)};
+    std::cout << "Listening on localhost:8080" << std::endl;
+
+    constexpr int limit = 10; // allow 10 ongoing sessions
+    async::channel<subscription> sub_manager; (1)
+
+    co_await join( (2)
+      run_blockchain_info(sub_manager),
+      async::with( (3)
+        async::wait_group(
+            asio::cancellation_type::all,
+            asio::cancellation_type::all),
+        [&](async::wait_group & sessions) -> async::promise<void>
+        {
+          while (!co_await async::this_coro::cancelled) (4)
+          {
+            if (sessions.size() >= limit) (5)
+              co_await sessions.wait_one();
+
+            auto conn = co_await acc.async_accept(); (6)
+            sessions.push_back( (7)
+                run_session(
+                    beast::websocket::stream<socket_type>{std::move(conn)},
+                    sub_manager));
+          }
+        })
+      );
+
+    co_return 0;
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    1Create the channel to manage subscriptions
    2Use join to run both tasks in parallel.
    3Use an async scope to provide a wait_group.
    4Run until cancelled.
    5When we’ve reached the limit we wait for one task to complete.
    6Wait for a new connection.
    7Insert the session into the wait_group.
    +
    +
    +

    Main is using join because one task failing should cancel the other one.

    +
    +
    +
    +
    +

    ← Previous: echo server | ↑ Up: Tutorial | ⌂ Home: Documentation boost.async | Next: delay op →

    +
    +
    + + + \ No newline at end of file diff --git a/promise.html b/promise.html new file mode 100644 index 00000000..54211c44 --- /dev/null +++ b/promise.html @@ -0,0 +1,915 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/promise.hpp

    +
    +
    +

    A promise is an eager coroutine that can co_await and co_return values. That is, it cannot use co_yield.

    +
    +
    +
    +
    async::promise<void> delay(std::chrono::milliseconds ms)
+{
+  asio::steady_timer tim{co_await async::this_coro::executor, ms};
+  co_await tim.async_wait(async::use_op);
+}
+
+async::main co_main(int argc, char *argv[])
+{
+  co_await delay(std::chrono::milliseconds(50));
+  co_return 0;
+}
    +
    +
    +
    +

    Promises can also be used to spawn tasks easily.

    +
    +
    +

    Promises are by default attached. +This means, that a cancellation is sent when the promise handles goes out of scope.

    +
    +
    +

    A promise can be detached by calling detach or by using the prefix + operator.

    +
    +
    +
    +
    async::promise<void> my_task();
+
+async::main co_main(int argc, char *argv[])
+{
+  +my_task(); (1)
+  co_await delay(std::chrono::milliseconds(50));
+  co_return 0;
+}
    +
    +
    +
    + + + + + +
    1By using + the task gets detached. Without it, the compiler would generate a nodiscard warning.
    +
    +
    +

    Executor

    +
    +

    The executor is taken from the thread_local get_executor function, unless a asio::executor_arg is used +in any position followed by the executor argument.

    +
    +
    +
    +
    async::promise<int> my_gen(asio::executor_arg_t, asio::io_context::executor_type exec_to_use);
    +
    +
    +
    +
    +

    Memory Resource

    +
    +

    The memory resource is taken from the thread_local get_default_resource function, +unless a std::allocator_arg is used in any position followed by a polymorphic_allocator argument.

    +
    +
    +
    +
    async::promise<int> my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<void> alloc);
    +
    +
    +
    +
    +

    Outline

    +
    +
    +
    template<typename Return>
+struct [[nodiscard]] promise
+{
+    promise(promise &&lhs) noexcept;
+    promise& operator=(promise && lhs) noexcept;
+
+    // enable `co_await`. (1)
+    auto operator co_await ();
+
+    // Ignore the return value, i.e. detach it. (2)
+    void operator +() &&;
+
+    // Cancel the promise.
+    void cancel(asio::cancellation_type ct = asio::cancellation_type::all);
+
+    // Check if the result is ready
+    bool ready() const;
+    // Check if the promise can be awaited.
+    explicit operator bool () const; (3)
+
+    // Detach or attach
+    bool attached() const;
+    void detach();
+    void attach();
+    // Get the return value if ready - otherwise throw
+    Return get();
+};
    +
    +
    +
    + + + + + + + + + + + + + +
    1Supports Interrupt Wait
    2This allows to spawn promised with a simple +my_task() expression.
    3This allows code like while (p) co_await p;
    +
    +
    +
    +

    Promise

    +
    +

    The coroutine promise (promise::promise_type) has the following properties.

    +
    +
    + +
    +
    +
    +
    +
    +

    ← Previous: async/main.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/generator.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/reference.html b/reference.html index de7f6d8c..62598483 100644 --- a/reference.html +++ b/reference.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -3141,7 +3143,7 @@

    async/leaf.hpp

    diff --git a/result.html b/result.html new file mode 100644 index 00000000..aef675b8 --- /dev/null +++ b/result.html @@ -0,0 +1,804 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/result.hpp

    +
    +
    +

    Awaitables can be modified to return system::result or +std::tuple instead of using exceptions.

    +
    +
    +
    +
    // value only
+T res = co_await foo();
+
+// as result
+system::result<T, std::exception_ptr> res = co_await async::as_result(foo());
+
+// as tuple
+std::tuple<std::exception_ptr, T> res = co_await async::as_tuple(foo());
    +
    +
    +
    +

    Awaitables can also provide custom ways to handle results and tuples, +by providing await_resume overloads using async::as_result_tag and async::as_tuple_tag.:

    +
    +
    +
    +
    your_result_type await_resume(async::as_result_tag);
+your_tuple_type  await_resume(async::as_tuple_tag);
    +
    +
    +
    +

    This allows an awaitable to provide other error types than std::exception_ptr, +for example system::error_code. This is done by op and channel.

    +
    +
    +
    +
    // example of an op with result system::error_code, std::size_t
+system::result<std::size_t>                 await_resume(async::as_result_tag);
+std::tuple<system::error_code, std::size_t> await_resume(async::as_tuple_tag);
    +
    +
    +
    + + + + + +
    + + +Awaitables are still allowed to throw exceptions, e.g. for critical exceptions such as OOM. +
    +
    +
    +
    +
    +

    ← Previous: async/thread.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/async_for.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/run.html b/run.html new file mode 100644 index 00000000..46dacf6f --- /dev/null +++ b/run.html @@ -0,0 +1,790 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/run.hpp

    +
    +
    +

    The run function is similar to spawn but running synchronously. +It will internally setup an execution context and the memory resources.

    +
    +
    +

    This can be useful when integrating a piece of async code into a synchronous application.

    +
    +
    +

    Outline

    +
    +
    +
    // Run the task and return it's value or rethrow any exception.
+T run(task<T> t);
    +
    +
    +
    +
    +

    Example

    +
    +
    +
    async::task<int> work();
+
+int main(int argc, char *argv[])
+{
+  return run(work());
+}
    +
    +
    +
    +
    +
    +
    +

    ← Previous: async/spawn.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/thread.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/running_noop_coroutine_in_parallel.html b/running_noop_coroutine_in_parallel.html new file mode 100644 index 00000000..5535ef7b --- /dev/null +++ b/running_noop_coroutine_in_parallel.html @@ -0,0 +1,772 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Running noop coroutine in parallel

    +
    +
    +

    This benchmark uses an asio::experimental::channel that has a size of zero, +to read & write in parallel to it. It uses gather with async +and an awaitable_operator in the asio::awaitable.

    +
    +
    +
    +
    async::task<void> atest()
+{
+  asio::experimental::channel<void(system::error_code)> chan{co_await async::this_coro::executor, 0u};
+  for (std::size_t i = 0u; i < n; i++)
+    co_await async::gather(
+              chan.async_send(system::error_code{}, async::use_task),
+              chan.async_receive(async::use_task));
+}
+
+asio::awaitable<void> awtest()
+{
+  asio::experimental::channel<void(system::error_code)> chan{co_await async::this_coro::executor, 0u};
+  using boost::asio::experimental::awaitable_operators::operator&&;
+  for (std::size_t i = 0u; i < n; i++)
+    co_await (
+        chan.async_send(system::error_code{}, asio::use_awaitable)
+        &&
+        chan.async_receive(asio::use_awaitable));
+}
    +
    +
    + + +++++ + + + + + + + + + + + + + + + + + + + +
    Table 6. results for 3M times in ms
    gcc 12clang 16

    async

    1563

    1468

    awaitable

    2800

    2805

    +
    +
    +
    +

    ← Previous: Posting to an executor | ↑ Up: Benchmarks | ⌂ Home: Documentation boost.async | Next: Immediate →

    +
    +
    + + + \ No newline at end of file diff --git a/select.html b/select.html new file mode 100644 index 00000000..2d28e19a --- /dev/null +++ b/select.html @@ -0,0 +1,928 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/select.hpp

    +
    +
    +

    The select function can be used to co_await one awaitable out of a set of them.

    +
    +
    +

    It can be called as a variadic function with multiple awaitable or as on a range of awaitables.

    +
    +
    +
    +
    async::promise<void> task1();
+async::promise<void> task2();
+
+async::promise<void> do_wait()
+{
+  co_await async::select(task1(), task2()); (1)
+  std::vector<async::promise<void>> aws {task1(), task2()};
+  co_await async::select(aws); (2)
+}
    +
    +
    +
    + + + + + + + + + +
    1Wait for a variadic set of awaitables
    2wait for a vector of awaitables
    +
    +
    +

    The first parameter so select can be a uniform random bit generator.

    +
    +
    +
    Signatures of select
    +
    +
    extern promise<void> pv1, pv2;
+std::vector<promise<void>> pvv;
+
+std::mt1337 rdm{1};
+// if everything returns void select returns the index
+std::size_t r1 = co_await select(pv1, pv2);
+std::size_t r2 = co_await select(rdm, pv1, pv2);
+std::size_t r3 = co_await select(pvv);
+std::size_t r4 = co_await select(rdm, pvv);
+
+// variant if not everything is void. void become monostate
+extern promise<int> pi1, pi2;
+variant2::variant<monostate, int, int> r5 = co_await select(pv1, pi1, pi2);
+variant2::variant<monostate, int, int> r6 = co_await select(rdm, pv1, pi1, pi2);
+
+// a range returns a pair of the index and the result if non-void
+std::vector<promise<int>> piv;
+std::pair<std::size_t, int> r7 = co_await select(piv);
+std::pair<std::size_t, int> r8 = co_await select(rdm, piv);
    +
    +
    +
    +

    Interrupt Wait

    +
    +

    When arguments are passed as rvalue reference, the select will attempt to use .interrupt_await +on the awaitable to detach the not completed awaitables. If supported, the Awaitable must complete immediately. +If the select doesn’t detect the immediate completion, it will send a cancellation.

    +
    +
    +

    This means that you can reuse select like this:

    +
    +
    +
    +
    async::promise<void> do_wait()
+{
+  auto t1 = task1();
+  auto t2 = task2();
+  co_await async::select(t1, t2); (1)
+  co_await async::select(t1, t2); (2)
+}
    +
    +
    +
    + + + + + + + + + +
    1Wait for the first task to complete
    2Wait for the other task to complete
    +
    +
    +

    This is supported by promise, generator and gather.

    +
    +
    +

    The select will invoke the functions of the awaitable as if used in a co_await expression +or not evaluate them at all.

    +
    +
    +
    +

    left_select

    +
    +

    The left_select functions are like select but follow a strict left-to-right scan. +This can lead to starvation issues, which is why this is not the recommended default, but can +be useful for prioritization if proper care is taken.

    +
    +
    +
    +

    Outline

    +
    +
    +
    // Concept for the random number generator.
+template<typename G>
+  concept uniform_random_bit_generator =
+    requires ( G & g)
+    {
+      {typename std::decay_t<G>::result_type() } -> std::unsigned_integral; // is an unsigned integer type
+      // T	Returns the smallest value that G's operator() may return. The value is strictly less than G::max(). The function must be constexpr.
+      {std::decay_t<G>::min()} -> std::same_as<typename std::decay_t<G>::result_type>;
+      // T	Returns the largest value that G's operator() may return. The value is strictly greater than G::min(). The function must be constexpr.
+      {std::decay_t<G>::max()} -> std::same_as<typename std::decay_t<G>::result_type>;
+      {g()} -> std::same_as<typename std::decay_t<G>::result_type>;
+    } && (std::decay_t<G>::max() > std::decay_t<G>::min());
+
+
+// Variadic select with a custom random number generator
+template<asio::cancellation_type Ct = asio::cancellation_type::all,
+         uniform_random_bit_generator URBG, awaitable ... Promise>
+awaitable select(URBG && g, Promise && ... p);
+
+// Ranged select with a custom random number generator
+template<asio::cancellation_type Ct = asio::cancellation_type::all,
+         uniform_random_bit_generator URBG, range<awaitable> PromiseRange>
+awaitable select(URBG && g, PromiseRange && p);
+
+// Variadic select with the default random number generator
+template<asio::cancellation_type Ct = asio::cancellation_type::all, awaitable... Promise>
+awaitable select(Promise && ... p);
+
+// Ranged select with the default random number generator
+template<asio::cancellation_type Ct = asio::cancellation_type::all, range<awaitable>>
+awaitable select(PromiseRange && p);
+
+// Variadic left select
+template<asio::cancellation_type Ct = asio::cancellation_type::all, awaitable... Promise>
+awaitable left_select(Promise && ... p);
+
+// Ranged left select
+template<asio::cancellation_type Ct = asio::cancellation_type::all, range<awaitable>>
+awaitable left_select(PromiseRange && p);
    +
    +
    +
    + + + + + +
    + + +Selecting an empty range will cause an exception to be thrown. +
    +
    +
    +
    +
    +
    +

    ← Previous: async/with.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/gather.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/spawn.html b/spawn.html new file mode 100644 index 00000000..6456b8e0 --- /dev/null +++ b/spawn.html @@ -0,0 +1,803 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/spawn.hpp

    +
    +
    +

    The spawn functions allow to use task directly with asio:

    +
    +
    +
    +
    auto spawn(                            task<T>    && t, CompletionToken&& token);
+auto spawn(asio::io_context & context, task<T>    && t, CompletionToken&& token);
+auto spawn(Executor executor,          task<T>    && t, CompletionToken&& token);
    +
    +
    +
    +

    Spawn will post both ways, so it is safe to use task to run the task +on another executor and consume the result on the current one with use_op.

    +
    +
    +

    Example

    +
    +
    +
    async::task<int> work();
+
+int main(int argc, char *argv[])
+{
+  asio::io_context ctx{BOOST_ASIO_CONCURRENCY_HINT_1};
+  auto f = spawn(ctx, work(), asio::use_future);
+  ctx.run();
+
+  return f.get();
+}
    +
    +
    +
    + + + + + +
    + + +The caller needs to make sure that the executor is not running on multiple threads +concurrently, e,g, by using a single-threaded context. +
    +
    +
    +
    +
    +
    +

    ← Previous: async/wait_group.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/run.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/stackless.html b/stackless.html new file mode 100644 index 00000000..6803d62b --- /dev/null +++ b/stackless.html @@ -0,0 +1,805 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Stackless

    +
    +
    +

    C++20 coroutines are stackless, meaning they don’t have their own stack.

    +
    +
    +

    A stack in C++ describes the callstack, i.e. all the function frames stacked. +A function frame is the memory a function needs to operate, i.e. a slice of memory +to store its variables and information such as the return address.

    +
    +
    + + + + + +
    + + +The size of a function frame is known at compile time, but not outside the compile unit containing its definition. +
    +
    +
    +
    +
    int bar() {return 0;} // the deepest point of the stack
+int foo() {return bar();}
+
+int main()
+{
+    return bar();
+}
    +
    +
    +
    +

    The call stack in the above example is:

    +
    +
    +
    +
    main()
+  foo()
+    bar()
    +
    +
    +
    +
    +Diagram +
    +
    +
    +

    Coroutines can be implemented a stackful, which means that it allocates a fixes chunk of memory and stacks function frames similar to a thread. +C++20 coroutines are stackless, i.e. they only allocate their own frame and use the callers stack on resumption. Using our previous example:

    +
    +
    +
    +
    fictional_eager_coro_type<int> example()
+{
+    co_yield 0;
+    co_yield 1;
+}
+
+void nested_resume(fictional_eager_coro_type<int>& f)
+{
+    f.resume();
+}
+
+int main()
+{
+    auto f = example();
+    nested_resume(f);
+    f.reenter();
+    return 0;
+}
    +
    +
    +
    +

    This will yield a call stack similar to this:

    +
    +
    +
    +
    main()
+  f$example()
+  nested_resume()
+    f$example()
+  f$example()
    +
    +
    +
    +
    +Diagram +
    +
    +
    +

    The same applies if a coroutine gets moved accross threads.

    +
    +
    +
    +
    +

    ↑ Up: Technical Background | ⌂ Home: Documentation boost.async | Next: Lazy & eager →

    +
    +
    + + + \ No newline at end of file diff --git a/task.html b/task.html new file mode 100644 index 00000000..5adac594 --- /dev/null +++ b/task.html @@ -0,0 +1,874 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/task.hpp

    +
    +
    +

    A task is a lazy coroutine that can co_await and co_return values. That is, it cannot use co_yield.

    +
    +
    +
    +
    async::task<void> delay(std::chrono::milliseconds ms)
+{
+  asio::steady_timer tim{co_await async::this_coro::executor, ms};
+  co_await tim.async_wait(async::use_op);
+}
+
+async::main co_main(int argc, char *argv[])
+{
+  co_await delay(std::chrono::milliseconds(50));
+  co_return 0;
+}
    +
    +
    +
    +

    Unlike a promise, a task can be awaited or spawned on another executor than it was created on.

    +
    +
    +

    Executor

    +
    +

    Since a task it lazy, it does not need to have an executor on construction. +It rather attempts to take it from the caller or awaiter if present. +Otherwise, it’ll default to the thread_local executor.

    +
    +
    +
    +

    Memory Resource

    +
    +

    The memory resource is NOT taken from the thread_local get_default_resource function, +but pmr::get_default_resource(), +unless a `std::allocator_arg is used in any position followed by a polymorphic_allocator argument.

    +
    +
    +
    +
    async::task<int> my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<void> alloc);
    +
    +
    +
    +
    +

    Outline

    +
    +
    +
    template<typename Return>
+struct [[nodiscard]] task
+{
+    task(task &&lhs) noexcept = default;
+    task& operator=(task &&) noexcept = default;
+
+    // enable `co_await`
+    auto operator co_await ();
+
+};
    +
    +
    +
    + + + + + +
    + + +Tasks can be used synchronously from a sync function by calling run(my_task()). +
    +
    +
    +
    +

    Promise

    +
    +

    The task promise has the following properties.

    +
    +
    + +
    +
    +
    +

    use_task

    +
    +

    The use_task completion token can be used to create a task from an async_ function. +This is less efficient than use_op as it needs to allocate a coroutine frame, +but has an obvious return type and support Interrupt Wait.

    +
    +
    +
    +
    +
    +

    ← Previous: async/generator.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/detached.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/technical_background.html b/technical_background.html index 650b3548..3125e58a 100644 --- a/technical_background.html +++ b/technical_background.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial
  • Design @@ -889,7 +891,7 @@

    Lazy & eager

    diff --git a/this_coro.html b/this_coro.html new file mode 100644 index 00000000..8e34d2b6 --- /dev/null +++ b/this_coro.html @@ -0,0 +1,927 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/this_coro.hpp

    +
    +
    +

    The this_coro namespace provides utilities to access the internal state of a coroutine promise.

    +
    +
    +

    Pseudo-awaitables:

    +
    +
    +
    +
    // Awaitable type that returns the executor of the current coroutine.
+struct executor_t {}
+constexpr executor_t executor;
+
+// Awaitable type that returns the cancellation state of the current coroutine.
+struct cancellation_state_t {};
+constexpr cancellation_state_t cancellation_state;
+
+// Reset the cancellation state with custom or default filters.
+constexpr unspecified reset_cancellation_state();
+template<typename Filter>
+constexpr unspecified reset_cancellation_state(
+    Filter && filter);
+template<typename InFilter, typename OutFilter>
+constexpr unspecified reset_cancellation_state(
+    InFilter && in_filter,
+    OutFilter && out_filter);
+
+// get & set the throw_if_cancelled setting.
+unspecified throw_if_cancelled();
+unspecified throw_if_cancelled(bool value);
+
+// Set the cancellation source in a detached.
+unspecified reset_cancellation_source();
+unspecified reset_cancellation_source(asio::cancellation_slot slot);
+
+
+// get the allocator the promise
+struct allocator_t {};
+constexpr allocator_t allocator;
+
+// get the current cancellation state-type
+struct cancelled_t {};
+constexpr cancelled_t cancelled;
+
+// set the over-eager mode of a generator
+struct initial_t {};
+constexpr initial_t initial;
    +
    +
    +
    +

    Await Allocator

    +
    +

    The allocator of a coroutine supporting enable_await_allocator can be obtained the following way:

    +
    +
    +
    +
    co_await async::this_coro::allocator;
    +
    +
    +
    +

    In order to enable this for your own coroutine you can inherit enable_await_allocator with the CRTP pattern:

    +
    +
    +
    +
    struct my_promise : async::enable_await_allocator<my_promise>
+{
+  using allocator_type = __your_allocator_type__;
+  allocator_type get_allocator();
+};
    +
    +
    +
    + + + + + +
    + + +If available the allocator gets used by use_op +
    +
    +
    +
    +

    Await Executor

    +
    +

    The allocator of a coroutine supporting enable_await_executor can be obtained the following way:

    +
    +
    +
    +
    co_await async::this_coro::executor;
    +
    +
    +
    +

    In order to enable this for your own coroutine you can inherit enable_await_executor with the CRTP pattern:

    +
    +
    +
    +
    struct my_promise : async::enable_await_executor<my_promise>
+{
+  using executor_type = __your_executor_type__;
+  executor_type get_executor();
+};
    +
    +
    +
    + + + + + +
    + + +If available the executor gets used by use_op +
    +
    +
    +
    +

    Memory resource base

    +
    +

    The promise_memory_resource_base base of a promise will provide a get_allocator in the promise taken from +either the default resource or one passed following a std::allocator_arg argument. +Likewise, it will add operator new overloads so the coroutine uses the same memory resource for its frame allocation.

    +
    +
    +
    +

    Throw if cancelled

    +
    +

    The promise_throw_if_cancelled_base provides the basic options to allow operation to enable a coroutines +to turn throw an exception when another actual awaitable is awaited.

    +
    +
    +
    +
    co_await async::this_coro::throw_if_cancelled;
    +
    +
    +
    +
    +

    Cancellation state

    +
    +

    The promise_cancellation_base provides the basic options to allow operation to enable a coroutines +to have a cancellation_state that is resettable by +reset_cancellation_state

    +
    +
    +
    +
    co_await async::this_coro::reset_cancellation_state();
    +
    +
    +
    +

    For convenience there is also a short-cut to check the current cancellation status:

    +
    +
    +
    +
    asio::cancellation_type ct = (co_await async::this_coro::cancellation_state).cancelled();
+asio::cancellation_type ct = co_await async::this_coro::cancelled; // same as above
    +
    +
    +
    +
    +
    +
    +

    ← Previous: async/concepts.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/this_thread.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/this_thread.html b/this_thread.html new file mode 100644 index 00000000..51f4518e --- /dev/null +++ b/this_thread.html @@ -0,0 +1,814 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/this_thread.hpp

    +
    +
    +

    Since everything is single threaded this library provides an executor +& default memory-resource for every thread.

    +
    +
    +
    +
    namespace boost::async::this_thread
+{
+
+pmr::memory_resource* get_default_resource() noexcept; (1)
+pmr::memory_resource* set_default_resource(pmr::memory_resource* r) noexcept; (2)
+pmr::polymorphic_allocator<void> get_allocator(); (3)
+
+typename asio::io_context::executor_type & get_executor(); (4)
+void set_executor(asio::io_context::executor_type exec) noexcept; (5)
+
+}
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + +
    1Get the default resource - will be pmr::get_default_resource unless set
    2Set the default resource - returns the previously set one
    3Get an allocator wrapping (1)
    4Get the executor of the thread - throws if not set
    5Set the executor of the current thread.
    +
    +
    +

    The coroutines will use these as defaults, but keep a copy just in case.

    +
    +
    + + + + + +
    + + +The only exception is the initialization of an async-operation, +which will use the this_thread::executor to rethrow from. +
    +
    +
    +
    +
    +

    ← Previous: async/this_coro.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/channel.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/thread.html b/thread.html new file mode 100644 index 00000000..376df7b1 --- /dev/null +++ b/thread.html @@ -0,0 +1,931 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    async/thread.hpp

    +
    +
    +

    The thread type is another way to create an environment that is similar to main, but doesn’t use a signal_set.

    +
    +
    +
    +
    async::thread my_thread()
+{
+  auto exec = co_await async::this_coro::executor;             (1)
+  asio::steady_timer tim{exec, std::chrono::milliseconds(50)}; (2)
+  co_await tim.async_wait(async::use_op);                      (3)
+  co_return 0;
+}
    +
    +
    +
    + + + + + + + + + + + + + +
    1get the executor thread running on
    2Use it with an asio object
    3co_await an async operation
    +
    +
    +

    To use a thread you can use it like a std::thread:

    +
    +
    +
    +
    int main(int argc, char * argv[])
+{
+  auto thr = my_thread();
+  thr.join();
+  return 0;
+}
    +
    +
    +
    +

    A thread is also an awaitable (including cancellation).

    +
    +
    +
    +
    async::main co_main(int argc, char * argv[])
+{
+  auto thr = my_thread();
+  co_await thr;
+  co_return 0;
+}
    +
    +
    +
    + + + + + +
    + + +Destructing a detached thread will cause a hard stop (io_context::stop) and join the thread. +
    +
    +
    + + + + + +
    + + +Nothing in this library, except for awaiting a async/thread.hpp and async/spawn.hpp, is thread-safe. +If you need to transfer data across threads, you’ll need a thread-safe utility like asio::conrurrenct_channel. +You cannot share any async primitives between threads, +with the sole exception of being able to spawn a task onto another thread’s executor. +
    +
    +
    +

    Executor

    +
    +

    It will also create an asio::io_context to run on, which you can get through the this_coro::executor. +It will be assigned to the async::this_thread::get_executor() .

    +
    +
    +
    +

    Memory Resource

    +
    +

    It also creates a memory resource that will be used as a default for internal memory allocations. +It will be assigned to the thread_local to the async::this_thread::get_default_resoruce().

    +
    +
    +
    +

    Outline

    +
    +
    +
    struct thread
+{
+  // Send a cancellation signal
+  void cancel(asio::cancellation_type type = asio::cancellation_type::all);
+
+  // Add the functions similar to `std::thread`
+  void join();
+  bool joinable() const;
+  void detach();
+  // Allow the thread to be awaited
+  auto operator co_await() &-> detail::thread_awaitable; (1)
+  auto operator co_await() && -> detail::thread_awaitable; (2)
+
+  // Stops the io_context & joins the executor
+  ~thread();
+  /// Move constructible
+  thread(thread &&) noexcept = default;
+
+  using executor_type = executor;
+
+  using id = std::thread::id;
+  id get_id() const noexcept;
+
+  executor_type get_executor() const;
+};
    +
    +
    +
    + + + + + + + + + +
    1Supports Interrupt Wait
    2Always forward cancel
    +
    +
    +
    +

    Promise

    +
    +

    The thread promise has the following properties.

    +
    +
    + +
    +
    +
    +
    +
    +

    ← Previous: async/run.hpp | ↑ Up: Reference | ⌂ Home: Documentation boost.async | Next: async/result.hpp →

    +
    +
    + + + \ No newline at end of file diff --git a/threading.html b/threading.html new file mode 100644 index 00000000..7a1967fb --- /dev/null +++ b/threading.html @@ -0,0 +1,770 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Threading

    +
    +
    +

    This library is single-threaded by design, because this simplifies resumption +and thus more performant handling of synchronizations like select. +select would need to lock every selected awaitable to avoid data loss +which would need to be blocking and get worse with every additional element.

    +
    +
    + + + + + +
    + + +you can’t have any coroutines be resumed on a different thread than created on, +except for a task (e.g. using spawn). +
    +
    +
    +

    The main technical reason is that the most efficient way of switching coroutines is by returning the handle +of the new coroutine from await_suspend like this:

    +
    +
    +
    +
    struct my_awaitable
+{
+    bool await_ready();
+    std::coroutine_handle<T> await_suspend(std::coroutine_handle<U>);
+    void await_resume();
+};
    +
    +
    +
    +

    In this case, the awaiting coroutine will be suspended before await_suspend is called, +and the coroutine returned is resumed. This of course doesn’t work if we need to go through an executor.

    +
    +
    +

    This doesn’t only apply to awaited coroutines, but channels, too. +The channels in this library use an intrusive list of awaitables +and may return the handle of reading (and thus suspended) coroutine +from a write_operation’s await_suspend.

    +
    +
    +
    +
    +

    ← Previous: Associators | ↑ Up: Design | ⌂ Home: Documentation boost.async | Next: Reference →

    +
    +
    + + + \ No newline at end of file diff --git a/tour.html b/tour.html new file mode 100644 index 00000000..ab9c3833 --- /dev/null +++ b/tour.html @@ -0,0 +1,1015 @@ + + + + + + + + +Documentation boost.async + + + + + + + + +
    +
    +

    Tour

    +
    +
    +

    Entry into an async environment

    +
    +

    In order to use awaitables we need to be able to co_await them, i.e. be within a coroutine.

    +
    +
    +

    We got four ways to achieve this:

    +
    +
    +
    +
    async/main.hpp
    +
    +

    replace int main with a coroutine

    +
    +
    +
    +
    +
    +
    async::main co_main(int argc, char* argv[])
+{
+    // co_await things here
+    co_return 0;
+}
    +
    +
    +
    +
    +
    async/thread.hpp
    +
    +

    create a thread for the asynchronous environments

    +
    +
    +
    +
    +
    +
    async::thread my_thread()
+{
+    // co_await things here
+    co_return;
+}
+
+int main(int argc, char ** argv[])
+{
+    auto t = my_thread();
+    t.join();
+    return 0;
+}
    +
    +
    +
    +
    +
    async/task.hpp
    +
    +

    create a task and run or spawn it

    +
    +
    +
    +
    +
    +
    async::task<void> my_thread()
+{
+   // co_await things here
+   co_return;
+}
+
+int main(int argc, char ** argv[])
+{
+    async::run(my_task()); // sync
+    asio::io_context ctx;
+    async::spawn(ctx, my_task(), asio::detached); // async, refer to async for details
+    ctx.run();
+    return 0;
+}
    +
    +
    +
    +
    +

    Promises

    +
    +

    Promises are the recommended default coroutine type. +They’re eager and thus easily usable for ad-hoc concurrecy.

    +
    +
    +
    +
    async::promise<int> my_promise()
+{
+   co_await do_the_thing();
+   co_return 0;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+    // start the promise here
+    auto p = my_promise();
+    // do something else here
+    co_await do_the_other_thing();
+    // wait for the promise to complete
+    auto res = co_wait p;
+
+    co_return res;
+}
    +
    +
    +
    +
    +

    Tasks

    +
    +

    Tasks are lazy, which means they won’d do anything before awaited or spwaned.

    +
    +
    +
    +
    async::task<int> my_task()
+{
+   co_await do_the_thing();
+   co_return 0;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+    // create the task here
+    auto t = my_task();
+    // do something else here first
+    co_await do_the_other_thing();
+    // start and wait for the task to complete
+    auto res = co_wait t;
+    co_return res;
+}
    +
    +
    +
    +
    +

    Generator

    +
    +

    A generator is the only type in async that can co_yield values.

    +
    +
    +

    Generator are eager by default. Unlike std::generator +the async::generator can co_await and thus is asynchronous.

    +
    +
    +
    +
    async::generator<int> my_generator()
+{
+   for (int i = 0; i < 10; i++)
+    co_yield i;
+   co_return 10;
+}
+
+async::main co_main(int argc, char * argv[])
+{
+    // create the generator
+    auto g = my_generator();
+    while (g)
+        printf("Generator %d\n", co_await g);
+    co_return 0;
+}
    +
    +
    +
    +

    Values can be pushed into the generator, that will be returned from the co_yield.

    +
    +
    +
    +
    async::generator<double, int> my_eager_push_generator(int value)
+{
+   while (value != 0)
+       value = co_yield value * 0.1;
+   co_return std::numeric_limits<double>::quiet_NaN();
+}
+
+async::main co_main(int argc, char * argv[])
+{
+    // create the generator
+    auto g = my_generator(5);
+
+    assert(0.5 == co_await g(4)); // result of 5
+    assert(0.4 == co_await g(3)); // result of 4
+    assert(0.3 == co_await g(2)); // result of 3
+    assert(0.2 == co_await g(1)); // result of 2
+    assert(0.1 == co_await g(0)); // result of 1
+
+    // we let the coroutine go out of scope while suspended
+    // no need for another co_await of `g`
+
+    co_return 0;
+}
    +
    +
    +
    +

    A coroutine can also be made lazy using this_coro::initial.

    +
    +
    +
    +
    async::generator<double, int> my_eager_push_generator()
+{
+    auto value = co_await this_coro::initial;
+    while (value != 0)
+        value = co_yield value * 0.1;
+    co_return std::numeric_limits<double>::quiet_NaN();
+}
+
+async::main co_main(int argc, char * argv[])
+{
+    // create the generator
+    auto g = my_generator(); // lazy, so the generator waits for the first pushed value
+    assert(0.5 == co_await g(5)); // result of 5
+    assert(0.4 == co_await g(4)); // result of 4
+    assert(0.3 == co_await g(3)); // result of 3
+    assert(0.2 == co_await g(2)); // result of 2
+    assert(0.1 == co_await g(1)); // result of 1
+
+    // we let the coroutine go out of scope while suspended
+    // no need for another co_await of `g`
+
+    co_return 0;
+}
    +
    +
    +
    +
    +

    join

    +
    +

    If multiple awaitables work in parallel they can be awaited simultaneously with +join.

    +
    +
    +
    +
    async::promise<int> some_work();
+async::promise<double> more_work();
+
+async::main co_main(int argc, char * argv[])
+{
+    std::tuple<int, double> res = async::join(some_work(), more_work());
+    co_return 0;
+}
    +
    +
    +
    +
    +

    select

    +
    +

    If multiple awaitables work in parallel, +but we want to be notified if either completes, we shall use select.

    +
    +
    +
    +
    async::generator<int> some_data_source();
+async::generator<double> another_data_source();
+
+async::main co_main(int argc, char * argv[])
+{
+    auto g1 = some_data_source();
+    auto g2 = another_data_source();
+
+    int res1    = co_await g1;
+    double res2 = co_await g2;
+
+    printf("Result: %f", res1 * res2);
+
+    while (g1 && g2)
+    {
+        switch(variant2::variant<int, double> nx = co_await async::select(g1, g2))
+        {
+            case 0:
+                res1 = variant2::get<0>(nx);
+                break;
+            case 1:
+                res2 = variant2::get<1>(nx);
+                break;
+        }
+        printf("New result: %f", res1 * res2);
+    }
+
+    co_return 0;
+}
    +
    +
    +
    + + + + + +
    + + +select in this context will not cause any data loss. +
    +
    +
    +
    +
    +
    +

    ← Previous: Coroutine Primer | ↑ Up: Documentation boost.async | Next: Tutorial →

    +
    +
    + + + \ No newline at end of file diff --git a/tutorial.html b/tutorial.html index 8d654fca..43a7bd02 100644 --- a/tutorial.html +++ b/tutorial.html @@ -672,6 +672,8 @@

    Documentation boost.async

  • Coroutine Primer
    • +
  • Tour +
  • Tutorial