diff --git a/doc/changelog.dox b/doc/changelog.dox index d67504e..a11d369 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -28,6 +28,123 @@ namespace cti { Following versions were released: +\subsection changelog-versions-4-0-0 4.0.0 + +Following methods and functions have been added: + +Various improvements to continuable_base: + +- \ref continuable_base::as for casting to a continuable_base with different arguments +- \ref continuable_base::finish for 'materializing' an intermediate chained continuable_base + +An asychronous initiation function comparable to std::async: + +The asynchronous facilities make it possible now to start with a handler +instead of a continuation: + +\code{.cpp} +async([] { + // ... +}).then(...); +\endcode + +- \ref async +- \ref async_on allows to specify an additional executor parameter + +The result class and modifying the asynchronous control flow + +Every continuation handler used in \ref continuable_base::then, \ref continuable_base::next +and \ref continuable_base::fail allows now to return a \ref result which represents +the asynchronous result. + +This allows recovering from failures or throwing of exception types from +handlers when exceptions are disabled. + +Result handling and +- \ref result +- \ref rethrow +- \ref cancel +- \ref terminate +- \ref make_result + +Special result types +- \ref empty_result +- \ref cancellation_result +- \ref exceptional_result + +Optimize 'ready' continuables: + +Continuables which are 'ready' and side effect free can now be unpacked +synchronously. Mainly such continuables are created through \ref make_ready_continuable, +\ref make_exceptional_continuable and \ref make_cancelling_continuable. + +- \ref continuable_base::is_ready +- \ref continuable_base::unpack +- \ref make_cancelling_continuable + +Including various helper tags for the underlying changed continuation object structure: + +- \ref signature_arg_t +- \ref is_ready_arg_t +- \ref unpack_arg_t +- \ref exception_arg_t +- \ref exception_t + +asio asynchronous initiate token: + +The \ref use_continuable_t special tag can be used to make (boost) asio +return a \ref continuable_base. + +- \ref use_continuable + +\code{.cpp} +#include +#include +#include + +// ... + +asio::tcp::resolver resolver(...); +resolver.async_resolve("127.0.0.1", "daytime", cti::use_continuable) + .then([](asio::udp::resolver::iterator iterator) { + // ... + }); +\endcode + +Iterating over an asynchronous control flow: + +The loop function was added which makes is possible to emulate an asynchronous loop, +that is comparable to a `co_await` with `for`. + +- \ref loop +- \ref loop_result +- \ref loop_break +- \ref loop_continue +- \ref range_loop +- \ref range_loop +- \ref plain_t +- \ref make_plain + +Synchronous wait transforms: + +The wait transforms allows to block the current thread until a \ref continuable_base +was resolved. + +- \ref transforms::wait +- \ref transforms::wait_for +- \ref transforms::wait_until + +Various changes: + +Many more unlisted changes including: + +- \ref work +- \ref continuation_capacity +- \ref promisify::with +- \ref void_arg_t + +Additional various bugfixes have been made. + \subsection changelog-versions-3-0-0 3.0.0 New helper functions diff --git a/doc/tutorial-promisify-continuables.dox b/doc/tutorial-promisify-continuables.dox index 246e5b1..aae2790 100644 --- a/doc/tutorial-promisify-continuables.dox +++ b/doc/tutorial-promisify-continuables.dox @@ -75,9 +75,9 @@ async_resolve("127.0.0.1", "daytime") Since version 4.0.0 continuable also supports asio async initiation tokens. -- Boost 1.70 and asio 1.13.0 is required for the async initiation -- Until boost 1.72 and asio 1.16.0 overhead through an additional type - erasure is added. It is recommeded to update to those versions. +- Boost 1.70 or asio 1.13.0 is required for the async initiation +- Until boost 1.72 or asio 1.16.0 overhead through an additional type + erasure is added. It is recommended to update to those versions. The special static variable \ref cti::use_continuable can be appended to any (boost) asio function that accepts a callback to make it return a \ref continuable_base. diff --git a/include/continuable/external/asio.hpp b/include/continuable/external/asio.hpp index abd3f4c..108e2be 100644 --- a/include/continuable/external/asio.hpp +++ b/include/continuable/external/asio.hpp @@ -36,10 +36,36 @@ namespace cti { /// Type used as an ASIO completion token to specify an asynchronous operation -/// should return a continuable. +/// that should return a continuable_base. +/// +/// - Boost 1.70 or asio 1.13.0 is required for the async initiation +/// - Until boost 1.72 or asio 1.16.0 overhead through an additional type +/// erasure is added. It is recommended to update to those versions. +/// +/// The special static variable use_continuable can be appended to any +/// (boost) asio function that accepts a callback to make it return a +/// continuable_base. +/// +/// ```cpp +/// #include +/// #include +/// #include +/// +/// // ... +/// +/// asio::tcp::resolver resolver(...); +/// resolver.async_resolve("127.0.0.1", "daytime", cti::use_continuable) +/// .then([](asio::udp::resolver::iterator iterator) { +/// // ... +/// }); +/// ``` +/// +/// \since 4.0.0 struct use_continuable_t {}; -/// Special value for instance of `asio_token_t`. +/// Special value for instance of `asio_token_t` +/// +/// \copydetails use_continuable_t constexpr use_continuable_t use_continuable{}; } // namespace cti @@ -58,8 +84,8 @@ public: Args... args) { return cti::detail::asio::initiate_make_continuable{}( [initiation = std::move(initiation), - init_args = - std::make_tuple(std::move(args)...)](auto&& promise) mutable { + init_args = std::make_tuple(std::move(args)...)]( + auto&& promise) mutable { cti::detail::traits::unpack( [initiation = std::move(initiation), handler = cti::detail::asio::promise_resolver_handler(