diff --git a/doc/tutorial-awaiting-continuables.dox b/doc/tutorial-awaiting-continuables.dox index 10cb9a9..13688b5 100644 --- a/doc/tutorial-awaiting-continuables.dox +++ b/doc/tutorial-awaiting-continuables.dox @@ -26,16 +26,86 @@ namespace cti { \tableofcontents -### Coroutines +\section tutorial-awaiting-continuables-usage Using co_await on continuables -Since version 2.0.0 coroutines (`co_await` and `co_return`) are supported by continuables when the underlying toolchain supports the TS. Currently this works in MSVC 2017 and Clang 5.0. -You have to enable this capability through the `CTI_CONTINUABLE_WITH_AWAIT` define in CMake. +Coroutines (`co_await`) are supported by continuables when the underlying +toolchain supports the TS. Currently this works in MSVC 2017 and Clang 5.0. -\endcodec++ +\attention You have to enable this feature through defining the + `CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE` preprocessor definition. + +It is possible to await for any \ref continuable_base as shown below: + +\code{.cpp} int i = co_await cti::make_continuable([](auto&& promise) { promise.set_value(0); }); \endcode +As described in \ref continuable_base::operator co_await() a continuable with +multiple arguments as result will wrap its result into a `std::tuple`: + +\code{.cpp} +std::tuple i = co_await cti::make_ready_continuable(0, 1); +\endcode + +\section tutorial-awaiting-continuables-await Using co_await with exceptions + +When a \ref continuable_base was resolved through an exception the exception +is rethrown from the `co_await` expression: + +\code{.cpp} +try { + auto response = co_await http_request("github.com"); +} catch(std::exception const& e) { + // Handle the exception +} +\endcode + +\section tutorial-awaiting-continuables-noexcept Using co_await with disabled exceptions + +In case the library is configured to use error codes or a custom +error type the return type of the co_await expression is changed. + +The result is returned through an internal proxy object which may +be queried for the error object: + +| Continuation type | co_await returns | +| : ------------------------------- | : -------------------------------- | +| `continuable_base with <>` | `unspecified` | +| `continuable_base with ` | `unspecified` | +| `continuable_base with ` | `unspecified>` | + +The interface of the proxy object is similar to the one proposed in +the `std::expected` proposal: + +\code{.cpp} +if (auto&& result = co_await http_request("github.com")) { + auto value = *result; +} else { + cti::error_type error = result.get_exception(); +} + +auto result = co_await http_request("github.com"); + +bool(result); +result.is_value(); +result.is_exception(); +*result; // Same as result.get_value() +result.get_value(); +result.get_exception(); +\endcode + + +\note It isn't possible as of now to use a \ref continuable_base + as return type from coroutines: +\code{.cpp} +cti::continuable do_sth() { + co_await http_request("github.com"); + // ... + co_return 0; +} +\endcode + */ } diff --git a/include/continuable/continuable-base.hpp b/include/continuable/continuable-base.hpp index 970e286..d8b9703 100644 --- a/include/continuable/continuable-base.hpp +++ b/include/continuable/continuable-base.hpp @@ -648,7 +648,7 @@ public: /// | `continuable_base with ` | `unspecified` | /// | `continuable_base with ` | `unspecified>` | /// The interface of the proxy object is similar to the one proposed in - /// the std::expected proposal: + /// the `std::expected` proposal: /// ```cpp /// if (auto&& result = co_await http_request("github.com")) { /// auto value = *result;