coffee/continuable
1
0
Fork 0
mirror of https://github.com/Naios/continuable.git synced 2026-02-15 22:59:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Some improvements to the documentation

Browse Source
This commit is contained in:
Denis Blank 2018-03-09 12:53:54 +01:00
parent a95246d45c
commit a9432b2c9a
12 changed files with 83 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/.gitignore vendored
View File

@ -1 +0,0 @@
doxygen/

4
doc/doxygen/Doxyfile
View File

@ -38,13 +38,13 @@ PROJECT_NAME = Continuable
# could be handy for archiving the generated documentation or if some version # could be handy for archiving the generated documentation or if some version
# control system is used. # control system is used.
PROJECT_NUMBER = PROJECT_NUMBER = 3.0.0
# Using the PROJECT_BRIEF tag one can provide an optional one line description # Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a # for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short. # quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF = "C++14 allocation aware futures (supporting then, error handling, co_await and compositions)" PROJECT_BRIEF =
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55 # in the documentation. The maximum height of the logo should not exceed 55

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

@ -47,6 +47,10 @@
#include <continuable/detail/util.hpp> #include <continuable/detail/util.hpp>
namespace cti { namespace cti {
/// \defgroup Base Base
/// provides classes and functions to create continuable_base objects.
/// \{
/// Represents a tag which can be placed first in a signature /// Represents a tag which can be placed first in a signature
/// in order to overload callables with the asynchronous result /// in order to overload callables with the asynchronous result
/// as well as an error. /// as well as an error.
@ -105,8 +109,7 @@ using detail::base::is_continuable;
/// \note Nearly all methods of the cti::continuable_base are required to be /// \note Nearly all methods of the cti::continuable_base are required to be
/// called as r-value. This is required because the continuable carries /// called as r-value. This is required because the continuable carries
/// variables which are consumed when the object is transformed as part /// variables which are consumed when the object is transformed as part
/// of a method call. You may copy a continuable which underlying /// of a method call.
/// storages are copyable to split the call hierarchy into multiple parts.
/// ///
/// \attention The continuable_base objects aren't intended to be stored. /// \attention The continuable_base objects aren't intended to be stored.
/// If you want to store a continuble_base you should always /// If you want to store a continuble_base you should always
@ -612,12 +615,12 @@ public:
/// \cond false /// \cond false
#ifdef CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE #ifdef CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE
/// \endcond /// \endcond
/// Implements the operator for awaiting on continuables using co_await. /// Implements the operator for awaiting on continuables using `co_await`.
/// ///
/// The operator is only enabled if `CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE` /// The operator is only enabled if `CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE`
/// is defined and the toolchain supports experimental coroutines. /// is defined and the toolchain supports experimental coroutines.
/// ///
/// The return type of the co_await expression is specified as following: /// The return type of the `co_await` expression is specified as following:
/// | Continuation type | co_await returns | /// | Continuation type | co_await returns |
/// | : ------------------------------- | : -------------------------------- | /// | : ------------------------------- | : -------------------------------- |
/// | `continuable_base with <>` | `void` | /// | `continuable_base with <>` | `void` |
@ -702,20 +705,20 @@ private:
} }
}; };
/// Creates a continuable_base from a callback taking function. /// Creates a continuable_base from a promise/callback taking function.
/// ///
/// \tparam Args The types (signature hint) the given callback is called with. /// \tparam Args The types (signature hint) the given promise is resolved with.
/// * **Some arguments** indicate the types the callback will be invoked with. /// * **Some arguments** indicate the types the promise will be invoked with.
/// ```cpp /// ```cpp
/// auto ct = cti::make_continuable<int, std::string>([](auto&& callback) { /// auto ct = cti::make_continuable<int, std::string>([](auto&& promise) {
/// std::forward<decltype(callback)>(callback)(200, "<html>...</html>"); /// promise.set_value(200, "<html>...</html>");
/// }); /// });
/// ``` /// ```
/// * **void as argument** indicates that the callback will be invoked /// * `void` **as argument** indicates that the promise will be invoked
/// with no arguments: /// with no arguments:
/// ```cpp /// ```cpp
/// auto ct = cti::make_continuable<void>([](auto&& callback) { /// auto ct = cti::make_continuable<void>([](auto&& promise) {
/// std::forward<decltype(callback)>(callback)(); /// promise.set_value();
/// }); /// });
/// ``` /// ```
/// * **No arguments** Since version 3.0.0 make_continuable always requires /// * **No arguments** Since version 3.0.0 make_continuable always requires
@ -726,13 +729,13 @@ private:
/// the continuable right after creation. /// the continuable right after creation.
/// ```cpp /// ```cpp
/// // This won't work because the arguments are missing: /// // This won't work because the arguments are missing:
/// auto ct = cti::make_continuable([](auto&& callback) { /// auto ct = cti::make_continuable([](auto&& promise) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c'); /// promise.set_value(0.f, 'c');
/// }); /// });
/// ///
/// // However, you are allowed to do this: /// // However, you are allowed to do this:
/// continuable<float, char> ct = [](auto&& callback) { /// cti::continuable<float, char> ct = [](auto&& promise) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c'); /// promise.set_value(callback)(0.f, 'c');
/// }; /// };
/// ``` /// ```
/// ///
@ -772,13 +775,19 @@ private:
/// }); /// });
/// ``` /// ```
/// ///
/// \returns A continuable_base with unknown template parameters which /// \returns A continuable_base with unspecified template parameters which
/// wraps the given continuation. /// wraps the given continuation.
/// In order to convert the continuable_base to a known type /// In order to convert the continuable_base to a known type
/// you need to apply type erasure. /// you need to apply type erasure through the
/// \link cti::continuable continuable\endlink or
/// \link cti::promise promise\endlink facilities.
/// ///
/// \note You should always turn the callback into a r-value if possible /// \note You should always turn the callback/promise into a r-value if possible
/// (`std::move` or `std::forward`) for qualifier correct invokation. /// (`std::move` or `std::forward`) for qualifier correct invokation.
/// Additionally it's important to know that all continuable promises
/// are callbacks and just expose their call operator nicely through
/// \link cti::promise_base::set_value set_value \endlink and
/// \link cti::promise_base::set_exception set_exception \endlink.
/// ///
/// \since 1.0.0 /// \since 1.0.0
template <typename... Args, typename Continuation> template <typename... Args, typename Continuation>
@ -860,6 +869,7 @@ constexpr auto make_exceptional_continuable(Exception&& exception) {
std::move(exception)); std::move(exception));
}); });
} }
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_BASE_HPP_INCLUDED #endif // CONTINUABLE_BASE_HPP_INCLUDED

8
include/continuable/continuable-compositions.hpp
View File

@ -43,6 +43,11 @@
#include <continuable/detail/range.hpp> #include <continuable/detail/range.hpp>
namespace cti { namespace cti {
/// \defgroup Compositioning Compositions
/// provides functions to connect \link continuable_base
/// continuable_bases\endlink through various strategies.
/// \{
/// Connects the given arguments with an all logic. /// Connects the given arguments with an all logic.
/// All continuables contained inside the given nested pack are /// All continuables contained inside the given nested pack are
/// invoked at once. On completion the final handler is called /// invoked at once. On completion the final handler is called
@ -251,7 +256,7 @@ auto when_any(Iterator begin, Iterator end) {
/// Populates a homogeneous container from the given arguments. /// Populates a homogeneous container from the given arguments.
/// All arguments need to be convertible to the first one, /// All arguments need to be convertible to the first one,
/// by default std::vector is used as container type. /// by default `std::vector` is used as container type.
/// ///
/// This method mainly helps to create a homogeneous container from /// This method mainly helps to create a homogeneous container from
/// a runtime known count of continuables which type isn't exactly known. /// a runtime known count of continuables which type isn't exactly known.
@ -291,6 +296,7 @@ populate(First&& first, Args&&... args) {
0, ((void)container.emplace_back(std::forward<Args>(args)), 0)...}; 0, ((void)container.emplace_back(std::forward<Args>(args)), 0)...};
return container; // RVO return container; // RVO
} }
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_COMPOSITIONS_HPP_INCLUDED #endif // CONTINUABLE_COMPOSITIONS_HPP_INCLUDED

5
include/continuable/continuable-promise-base.hpp
View File

@ -39,6 +39,10 @@
#include <continuable/detail/util.hpp> #include <continuable/detail/util.hpp>
namespace cti { namespace cti {
/// \defgroup Base Base
/// provides classes and functions to create continuable_base objects.
/// \{
/// The promise_base makes it possible to resolve an asynchronous /// The promise_base makes it possible to resolve an asynchronous
/// continuable through it's result or through an error type. /// continuable through it's result or through an error type.
/// ///
@ -110,6 +114,7 @@ public:
std::move(data_)(detail::types::dispatch_error_tag{}, std::move(exception)); std::move(data_)(detail::types::dispatch_error_tag{}, std::move(exception));
} }
}; };
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_PROMISE_BASE_HPP_INCLUDED #endif // CONTINUABLE_PROMISE_BASE_HPP_INCLUDED

6
include/continuable/continuable-promisify.hpp
View File

@ -37,6 +37,11 @@
#include <continuable/detail/promisify.hpp> #include <continuable/detail/promisify.hpp>
namespace cti { namespace cti {
/// \defgroup Promisify Promisify
/// provides helper methods to convert various callback styles to
/// \link continuable_base continuable_bases\endlink.
/// \{
/// Helper class for converting callback taking callable types into a /// Helper class for converting callback taking callable types into a
/// a continuable. Various styles are supported. /// a continuable. Various styles are supported.
/// - `from_asio`: Converts callback taking callable types into continuables /// - `from_asio`: Converts callback taking callable types into continuables
@ -81,6 +86,7 @@ public:
std::forward<Callable>(callable), std::forward<Args>(args)...); std::forward<Callable>(callable), std::forward<Args>(args)...);
} }
}; };
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_PROMISIFY_HPP_INCLUDED #endif // CONTINUABLE_PROMISIFY_HPP_INCLUDED

7
include/continuable/continuable-testing.hpp
View File

@ -34,6 +34,11 @@
#include <continuable/detail/testing.hpp> #include <continuable/detail/testing.hpp>
#include <continuable/detail/traits.hpp> #include <continuable/detail/traits.hpp>
/// \defgroup Testing Testing
/// provides macro shortcuts for testing asynchronous continuations through
/// GTest.
/// \{
/// Asserts that the final callback of the given continuable was called /// Asserts that the final callback of the given continuable was called
/// with any result. /// with any result.
/// ///
@ -162,4 +167,6 @@
ASSERT_ASYNC_BINARY_EXCEPTION_VALIDATION( \ ASSERT_ASYNC_BINARY_EXCEPTION_VALIDATION( \
cti::detail::testing::asserting_eq_check(), __VA_ARGS__) cti::detail::testing::asserting_eq_check(), __VA_ARGS__)
//// \}
#endif // CONTINUABLE_TESTING_HPP_INCLUDED #endif // CONTINUABLE_TESTING_HPP_INCLUDED

6
include/continuable/continuable-trait.hpp
View File

@ -39,6 +39,11 @@
#include <continuable/detail/types.hpp> #include <continuable/detail/types.hpp>
namespace cti { namespace cti {
/// \defgroup Types Types
/// provides the \link cti::continuable continuable\endlink and \link
/// cti::promise promise\endlink facility for type erasure.
/// \{
/// Trait to retrieve a continuable_base type with a given type-erasure backend. /// Trait to retrieve a continuable_base type with a given type-erasure backend.
/// ///
/// Every object may me used as type-erasure backend as long as the /// Every object may me used as type-erasure backend as long as the
@ -69,6 +74,7 @@ public:
continuable_base<ContinuationWrapper<sizeof(callback), void(promise)>, continuable_base<ContinuationWrapper<sizeof(callback), void(promise)>,
detail::hints::signature_hint_tag<Args...>>; detail::hints::signature_hint_tag<Args...>>;
}; };
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_TRAIT_HPP_INCLUDED #endif // CONTINUABLE_TRAIT_HPP_INCLUDED

5
include/continuable/continuable-transforms.hpp
View File

@ -35,6 +35,10 @@
#include <continuable/detail/types.hpp> #include <continuable/detail/types.hpp>
namespace cti { namespace cti {
/// \defgroup Transforms Transforms
/// provides utilities to convert \link continuable_base continuable_bases\endlink to other types (`std::future`).
/// \{
/// A callable tag object which marks a wrapped callable object /// A callable tag object which marks a wrapped callable object
/// as continuable transformation which enables some useful overloads. /// as continuable transformation which enables some useful overloads.
/// ///
@ -96,6 +100,7 @@ inline auto flatten() {
return std::forward<decltype(continuable)>(continuable).fail([](auto&&) {}); return std::forward<decltype(continuable)>(continuable).fail([](auto&&) {});
}); });
} }
/// \}
} // namespace transforms } // namespace transforms
} // namespace cti } // namespace cti

5
include/continuable/continuable-traverse-async.hpp
View File

@ -36,6 +36,10 @@
#include <continuable/detail/traverse-async.hpp> #include <continuable/detail/traverse-async.hpp>
namespace cti { namespace cti {
/// \defgroup Traversal Traversal
/// provides functions to traverse and remap nested packs.
/// \{
/// A tag which is passed to the `operator()` of the visitor /// A tag which is passed to the `operator()` of the visitor
/// if an element is visited synchronously. /// if an element is visited synchronously.
/// ///
@ -118,6 +122,7 @@ auto traverse_pack_async(Visitor&& visitor, T&&... pack) {
return detail::traversal::apply_pack_transform_async( return detail::traversal::apply_pack_transform_async(
std::forward<Visitor>(visitor), std::forward<T>(pack)...); std::forward<Visitor>(visitor), std::forward<T>(pack)...);
} }
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_TRAVERSE_ASYNC_HPP_INCLUDED #endif // CONTINUABLE_TRAVERSE_ASYNC_HPP_INCLUDED

5
include/continuable/continuable-traverse.hpp
View File

@ -38,6 +38,10 @@
#include <continuable/detail/traverse.hpp> #include <continuable/detail/traverse.hpp>
namespace cti { namespace cti {
/// \defgroup Traversal Traversal
/// provides functions to traverse and remap nested packs.
/// \{
/// Maps the pack with the given mapper. /// Maps the pack with the given mapper.
/// ///
/// This function tries to visit all plain elements which may be wrapped in: /// This function tries to visit all plain elements which may be wrapped in:
@ -106,6 +110,7 @@ void traverse_pack(Mapper&& mapper, T&&... pack) {
std::forward<Mapper>(mapper), std::forward<Mapper>(mapper),
std::forward<T>(pack)...); std::forward<T>(pack)...);
} }
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_TRAVERSE_HPP_INCLUDED #endif // CONTINUABLE_TRAVERSE_HPP_INCLUDED

6
include/continuable/continuable-types.hpp
View File

@ -38,6 +38,11 @@
#include <continuable/continuable-trait.hpp> #include <continuable/continuable-trait.hpp>
namespace cti { namespace cti {
/// \defgroup Types Types
/// provides the \link cti::continuable continuable\endlink and \link
/// cti::promise promise\endlink facility for type erasure.
/// \{
// clang-format off // clang-format off
namespace detail { namespace detail {
/// A function which isn't size adjusted and move only /// A function which isn't size adjusted and move only
@ -80,6 +85,7 @@ using promise = typename detail::unique_trait_of<
// TODO sink // TODO sink
// clang-format on // clang-format on
/// \}
} // namespace cti } // namespace cti
#endif // CONTINUABLE_TYPES_HPP_INCLUDED #endif // CONTINUABLE_TYPES_HPP_INCLUDED