CustomAsioStreams

CustomAsioStreams is a collection of examples showing how to create custom streams that integrate nicely into the asio library. Some example also focus on asio::awaitable and c++20 coroutines.

Building

If you want to build this project you should define the CPM_SOURCE_CACHE env variable and point it to a folder to avoid downloading the dependencies multiple times. Boost and fmt will be installed to that directory.

I personally use Clion but the project should work nicely with any IDE that supports cmake.

Targets

CAS_coro_context_switching

Shows off how you can easily switch between executors (threads/strands/execution_contexts) using co_await and post.

Also shows how to make the int main() into an asio::awaitable<int> mainCo() coroutine. This is comparable to how you would make node.js asynchronous.

CAS_coro_basic_io_object

Shows how to implement a modern IO service and a modern IO object. In this example the AsyncStreams are implemented using asio::awaitable.

CAS_coro_advcd_io_object

Builds on the foundation of the CAS_coro_basic_io_object example.

• The friend declaration is removed.

• The MyAsyncStream forward declaration is removed.

• The Service shared_ptr is hidden from the user.

• The Service init call is hidden from the user.

• Adds two direct async functions. This is useful when using streams is overkill and all data is available instantly.

CAS_async_calls

Shows how to use different completion tokens to call various async function signatures. Shows how to handle exceptions and error_codes properly.

CAS_work_guards

Shows off different kinds of work guards and an example use case.

Fluff - CAS_coro_outcome_return

Shows how to return a boost::outcome from an asio::awaitable.

Fluff - CAS_iterator_concepts

Shows how to use the new c++20 iterator concepts defined in the <iterator> header.

TODO

• Revisit work_guards - Create a proper work guard example

• NewEx: Show how to use captured_self to control lifetimes.

• NewEx: Show how to use and implement cancellation in custom async functions.

• NewEx: Show how to store completion handlers in a vector

• NewEx: Show how the system executor is dangerous and how to exit it cleanly (use query)

Questions

• When is the first argument of post, dispatch, defer ever useful? It’s just a BAD FALLBACK when no bound executor is found. And if one is found it first post empty work to the FALLBACK and the dispatches from there to the associated executor. When is that EVER useful? post.hpp:63 https://www.boost.org/doc/libs/1_79_0/doc/html/boost_asio/reference/get_associated_executor/overload3.html

• Additionally, the naming of the asio parameters is not really intuitive, and it’s lacking parameter descriptions of the overloads of very popular functions post, dispatch, defer.

• Biggest issue for beginner is the lack of examples and documentation. Even parameter names or simple sentences explaining one possible use case would be very helpful. Especially parameter descriptions. Also maybe note what the different overloads are for.

About

This repository is a collection of useful snippets I wrote to help me understand asio better. Thanks sehe for helping me out over on stackoverflow.