/*
  Copyright(c) 2015 - 2020 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 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.

\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
*/
}