From 5fbc9c4a59dc5858a6e880d3c8a3b8dbe7951bfe Mon Sep 17 00:00:00 2001 From: Denis Blank Date: Sat, 4 Apr 2020 23:27:32 +0200 Subject: [PATCH] Some doc fixes --- doc/index.dox | 6 +-- doc/tutorial-promisify-continuables.dox | 27 +++++++++++++- doc/tutorial-transforming-continuables.dox | 43 +++++++++++++--------- include/continuable/continuable-base.hpp | 2 +- 4 files changed, 56 insertions(+), 22 deletions(-) diff --git a/doc/index.dox b/doc/index.dox index cdd3ef9..c237c35 100644 --- a/doc/index.dox +++ b/doc/index.dox @@ -1,5 +1,5 @@ /* - Copyright(c) 2015 - 2019 Denis Blank + Copyright(c) 2015 - 2020 Denis Blank Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files(the "Software"), to deal @@ -70,13 +70,13 @@ your personal experience in using the library to improve it. \note If you are using the library in your open-source or commercial project I would highly appreciate if you could give me a short notice so I can add you to a list of projects and companies using this library. - + \section mainpage-license License Continuable is licensed under the MIT license: > -> Copyright(c) 2015 - 2019 Denis Blank +> Copyright(c) 2015 - 2020 Denis Blank > > Permission is hereby granted, free of charge, to any person obtaining a copy > of this software and associated documentation files(the "Software"), to deal diff --git a/doc/tutorial-promisify-continuables.dox b/doc/tutorial-promisify-continuables.dox index c2206f2..baf5ae3 100644 --- a/doc/tutorial-promisify-continuables.dox +++ b/doc/tutorial-promisify-continuables.dox @@ -50,7 +50,7 @@ The default callback style is something like Continuable offers the \ref promisify::from method for such callback styles. See an example of how to promisify boost asio's `async_resolve` below: - + \code{.cpp} auto async_resolve(std::string host, std::string service) { return cti::promisify::from( @@ -70,5 +70,30 @@ async_resolve("127.0.0.1", "daytime") }); \endcode + +\section tutorial-promisify-continuables-boost-ct asio and boost::asio async completion tokens + +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. + +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. + +\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 */ } diff --git a/doc/tutorial-transforming-continuables.dox b/doc/tutorial-transforming-continuables.dox index f3e3778..99f5147 100644 --- a/doc/tutorial-transforming-continuables.dox +++ b/doc/tutorial-transforming-continuables.dox @@ -30,28 +30,37 @@ namespace cti { Sometimes it's required to change a \ref continuable_base object by its whole. Thus the library offers the ability to apply a transformation to any -\ref continuable_base through using \link continuable_base::apply apply \endlink -or \link continuable_base::operator | its operator | \endlink. +\ref continuable_base through using \link continuable_base::apply apply \endlink. -A transformation accepts a \ref continuable_base and returns -an arbitrary object. - -To create a transformation use the \ref make_transform function: - -\code{.cpp} -auto transform = cti::make_transform([] (auto&& continuable) { - // Change the continuable - return std::forward(continuable); -}); -\endcode +A transformation is a callable object that accepts a \ref continuable_base +and returns an arbitrary object The library provides several transforms already as part of the \ref cti::transforms namespace. +\section tutorial-transforming-continuables-wait Synchronous wait + +The library is capable of converting every asynchronous control flow +into a synchronous one through \ref transforms::wait, \ref transforms::wait_for +and \ref transforms::wait_until. + +\code{.cpp} +std::string response = http_request("github.com") + .apply(cti::transforms::wait()); + +std::string response = http_request("github.com") + .apply(cti::transforms::wait_for(std::chrono::seconds(5))); + +std::string response = http_request("github.com") + .apply(cti::transforms::wait_until(...)); +\endcode + +The current thread will be blocked until the result has arrived + \section tutorial-transforming-continuables-future Conversion into std::future The library is capable of converting (*futurizing*) every continuable into a -fitting `std::future` through the \ref transforms::futurize transform: +fitting `std::future` through the \ref transforms::to_future transform: \code{.cpp} std::future future = http_request("github.com") @@ -59,17 +68,17 @@ std::future future = http_request("github.com") // Do sth... return http_request("travis-ci.org") || http_request("atom.io"); }) - .apply(cti::transforms::futurize()); + .apply(cti::transforms::to_future()); // ^^^^^^^^ \endcode Multiple arguments which can't be handled by `std::future` itself are -converted into `std::tuple`, see \ref transforms::futurize for details. +converted into `std::tuple`, see \ref transforms::to_future for details. \code{.cpp} std::future> future = (http_request("travis-ci.org") && http_request("atom.io")) - .apply(cti::transforms::futurize()); + .apply(cti::transforms::to_future()); \endcode */ } diff --git a/include/continuable/continuable-base.hpp b/include/continuable/continuable-base.hpp index 5ea75b0..c685efe 100644 --- a/include/continuable/continuable-base.hpp +++ b/include/continuable/continuable-base.hpp @@ -623,7 +623,7 @@ public: /// Invalidates the continuable and returns its immediate invocation result. /// /// This method can be used to specialize the asynchronous control flow - /// based on whether the continuable ìs_ready at every time, + /// based on whether the continuable_base is_ready at every time, /// which is true for a continuable created through the following functions: /// - make_ready_continuable /// - make_exceptional_continuable