coffee/continuable
1
0
Fork 0
mirror of https://github.com/Naios/continuable.git synced 2025-12-06 16:56:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add a documentation to make_continuable.

Browse Source
This commit is contained in:
Denis Blank 2017-02-26 21:21:37 +01:00
parent 9ab4fd7758
commit 6edce3bcaa
3 changed files with 2575 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -48,6 +48,8 @@ bld/
# Visual Studo 2015 cache/options directory # Visual Studo 2015 cache/options directory
.vs/ .vs/
doc/doxygen/
format.sh format.sh
push.sh push.sh
commit.sh commit.sh

2493
doc/Doxyfile Normal file
View File

File diff suppressed because it is too large Load Diff

84
include/continuable/continuable-base.hpp
View File

@ -1334,14 +1334,90 @@ private:
} }
}; };
template <typename... Args, typename T> /// Creates a \ref continuable_base from a callback taking function.
auto make_continuable(T&& continuation) { ///
/// \tparam Args The types (signature hint) the given callback is called with.
/// * **Some arguments** indicate the types the callback will be invoked with.
/// ```cpp
/// auto ct = cti::make_continuable<int, std::string>([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(200, "<html>...</html>");
/// });
/// ```
/// * **void as argument** indicates that the callback will be invoked
/// with no arguments:
/// ```cpp
/// auto ct = cti::make_continuable<void>([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)();
/// });
/// ```
/// * **No arguments** indicate that the types are unknown.
/// You should always give the type hint a callback is called with because
/// it's required for intermediate actions like connecting continuables.
/// You may omit the signature hint if you are erasing the type of
/// the continuable right after creation.
/// ```cpp
/// // Never do this:
/// auto ct = cti::make_continuable([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c');
/// });
///
/// // However, you may do this:
/// continuable<float, char> ct = cti::make_continuable([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c');
/// });
/// ```
///
/// \param continuation The continuation the continuable is created from.
/// The continuation must be a functional type accepting a callback parameter
/// which represents the object invokable with the asynchronous result of this
/// continuable.
/// ```cpp
/// auto ct = cti::make_continuable([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)("result");
/// });
/// ```
/// The callback may be stored or moved.
/// In some cases the callback may be copied if supported by the underlying
/// callback chain, in order to invoke the call chain multiple times.
/// It's recommended to accept any callback instead of erasing it.
/// ```cpp
/// // Good practice:
/// auto ct = cti::make_continuable([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)("result");
/// });
///
/// // Good practice using a functional object:
/// struct Continuation {
/// template<typename T>
/// void operator() (T&& continuation) const {
/// // ...
/// }
/// }
///
/// auto ct = cti::make_continuable(Continuation{});
///
/// // Bad practice (because of unnecessary type erasure):
/// auto ct = cti::make_continuable(
/// [](std::function<void(std::string)> callback) {
/// callback("result");
/// });
/// ```
///
/// \returns A \ref continuable_base with unknown template parameters which
/// wraps the given continuation.
///
/// \note You should always turn the callback into a r-value if possible
/// (`std::move` or `std::forward`) for qualifier correct invokation.
///
/// \since version 1.0.0
template <typename... Args, typename Continuation>
auto make_continuable(Continuation&& continuation) {
auto hint = detail::compose::annotating::extract( auto hint = detail::compose::annotating::extract(
detail::util::identity_of(continuation), detail::util::identity_of(continuation),
detail::util::identity<Args...>{}); detail::util::identity<Args...>{});
return detail::base::make_continuable_base(std::forward<T>(continuation), return detail::base::make_continuable_base(
hint); std::forward<Continuation>(continuation), hint);
} }
template <typename First, typename Second, typename... Rest> template <typename First, typename Second, typename... Rest>