mirror of
https://github.com/Naios/continuable.git
synced 2025-12-06 08:46:44 +08:00
100 lines
3.8 KiB
Plaintext
100 lines
3.8 KiB
Plaintext
/*
|
|
Copyright(c) 2015 - 2019 Denis Blank <denis.blank at outlook dot com>
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files(the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions :
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
SOFTWARE.
|
|
*/
|
|
|
|
namespace cti {
|
|
/** \page tutorial-promisify-continuables Promisify functions
|
|
\brief Explains how to promisify callback taking functions into a \ref continuable_base.
|
|
|
|
\tableofcontents
|
|
|
|
\section tutorial-promisify-continuables-promisify Promisification and continuables
|
|
|
|
The promisification has a longer history in the JavaScript world where
|
|
the legacy way of asynchronous programming was the usage of callbacks of the
|
|
form \code{.js}function(error, result...)\endcode. The ideal way of dealing
|
|
with such an asynchronous result is to return a promise and soon utility
|
|
helpers were provided to do so.
|
|
|
|
The usage of callbacks to represent an asynchronous result is still a popular
|
|
way nowadays. Thus the library provides the \ref promisify helper class
|
|
which makes it possible to convert callback taking functions of various styles
|
|
into one that returns a \ref continuable_base instead.
|
|
|
|
\note Providing promisified APIs for other popular libraries is out of
|
|
scope for this library. However contributions are highly welcome to
|
|
add more conversion helpers for other commonly used callback styles.
|
|
|
|
\section tutorial-promisify-continuables-boost Promisify boost::asio
|
|
|
|
The default callback style is something like
|
|
\code{.js}function(error, result...)\endcode as described above.
|
|
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<asio::ip::udp::resolver::iterator>::from(
|
|
[&](auto&&... args) {
|
|
resolver_.async_resolve(std::forward<decltype(args)>(args)...);
|
|
},
|
|
std::move(host), std::move(service));
|
|
}
|
|
\endcode
|
|
|
|
Then it should be possible to use `asio::async_resolve` like this:
|
|
|
|
\code{.cpp}
|
|
async_resolve("127.0.0.1", "daytime")
|
|
.then([](udp::resolver::iterator iterator) {
|
|
// ...
|
|
});
|
|
\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 <continuable/continuable.hpp>
|
|
#include <continuable/external/asio.hpp>
|
|
#include <asio.hpp>
|
|
|
|
// ...
|
|
|
|
asio::tcp::resolver resolver(...);
|
|
resolver.async_resolve("127.0.0.1", "daytime", cti::use_continuable)
|
|
.then([](asio::udp::resolver::iterator iterator) {
|
|
// ...
|
|
});
|
|
\endcode
|
|
*/
|
|
}
|