coffee/continuable
1
0
Fork 0
mirror of https://github.com/Naios/continuable.git synced 2025-12-08 01:36:46 +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
# control system is used.
PROJECT_NUMBER =
PROJECT_NUMBER = 3.0.0
# 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
# 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
# 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>
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
/// in order to overload callables with the asynchronous result
/// 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
/// called as r-value. This is required because the continuable carries
/// variables which are consumed when the object is transformed as part
/// of a method call. You may copy a continuable which underlying
/// storages are copyable to split the call hierarchy into multiple parts.
/// of a method call.
///
/// \attention The continuable_base objects aren't intended to be stored.
/// If you want to store a continuble_base you should always
@ -612,12 +615,12 @@ public:
/// \cond false
#ifdef CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE
/// \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`
/// 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 |
/// | : ------------------------------- | : -------------------------------- |
/// | `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.
/// * **Some arguments** indicate the types the callback will be invoked with.
/// \tparam Args The types (signature hint) the given promise is resolved with.
/// * **Some arguments** indicate the types the promise will be invoked with.
/// ```cpp
/// auto ct = cti::make_continuable<int, std::string>([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(200, "<html>...</html>");
/// auto ct = cti::make_continuable<int, std::string>([](auto&& promise) {
/// 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:
/// ```cpp
/// auto ct = cti::make_continuable<void>([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)();
/// auto ct = cti::make_continuable<void>([](auto&& promise) {
/// promise.set_value();
/// });
/// ```
/// * **No arguments** Since version 3.0.0 make_continuable always requires
@ -726,13 +729,13 @@ private:
/// the continuable right after creation.
/// ```cpp
/// // This won't work because the arguments are missing:
/// auto ct = cti::make_continuable([](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c');
/// auto ct = cti::make_continuable([](auto&& promise) {
/// promise.set_value(0.f, 'c');
/// });
///
/// // However, you are allowed to do this:
/// continuable<float, char> ct = [](auto&& callback) {
/// std::forward<decltype(callback)>(callback)(0.f, 'c');
/// cti::continuable<float, char> ct = [](auto&& promise) {
/// 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.
/// 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.
/// 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
template <typename... Args, typename Continuation>
@ -860,6 +869,7 @@ constexpr auto make_exceptional_continuable(Exception&& exception) {
std::move(exception));
});
}
/// \}
} // namespace cti
#endif // CONTINUABLE_BASE_HPP_INCLUDED

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

@ -43,6 +43,11 @@
#include <continuable/detail/range.hpp>
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.
/// All continuables contained inside the given nested pack are
/// 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.
/// 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
/// 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)...};
return container; // RVO
}
/// \}
} // namespace cti
#endif // CONTINUABLE_COMPOSITIONS_HPP_INCLUDED

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

@ -39,6 +39,10 @@
#include <continuable/detail/util.hpp>
namespace cti {
/// \defgroup Base Base
/// provides classes and functions to create continuable_base objects.
/// \{
/// The promise_base makes it possible to resolve an asynchronous
/// 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));
}
};
/// \}
} // namespace cti
#endif // CONTINUABLE_PROMISE_BASE_HPP_INCLUDED

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

@ -37,6 +37,11 @@
#include <continuable/detail/promisify.hpp>
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
/// a continuable. Various styles are supported.
/// - `from_asio`: Converts callback taking callable types into continuables
@ -81,6 +86,7 @@ public:
std::forward<Callable>(callable), std::forward<Args>(args)...);
}
};
/// \}
} // namespace cti
#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/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
/// with any result.
///
@ -162,4 +167,6 @@
ASSERT_ASYNC_BINARY_EXCEPTION_VALIDATION( \
cti::detail::testing::asserting_eq_check(), __VA_ARGS__)
//// \}
#endif // CONTINUABLE_TESTING_HPP_INCLUDED

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

@ -39,6 +39,11 @@
#include <continuable/detail/types.hpp>
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.
///
/// 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)>,
detail::hints::signature_hint_tag<Args...>>;
};
/// \}
} // namespace cti
#endif // CONTINUABLE_TRAIT_HPP_INCLUDED

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

@ -35,6 +35,10 @@
#include <continuable/detail/types.hpp>
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
/// as continuable transformation which enables some useful overloads.
///
@ -96,6 +100,7 @@ inline auto flatten() {
return std::forward<decltype(continuable)>(continuable).fail([](auto&&) {});
});
}
/// \}
} // namespace transforms
} // namespace cti

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

@ -36,6 +36,10 @@
#include <continuable/detail/traverse-async.hpp>
namespace cti {
/// \defgroup Traversal Traversal
/// provides functions to traverse and remap nested packs.
/// \{
/// A tag which is passed to the `operator()` of the visitor
/// 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(
std::forward<Visitor>(visitor), std::forward<T>(pack)...);
}
/// \}
} // namespace cti
#endif // CONTINUABLE_TRAVERSE_ASYNC_HPP_INCLUDED

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

@ -38,6 +38,10 @@
#include <continuable/detail/traverse.hpp>
namespace cti {
/// \defgroup Traversal Traversal
/// provides functions to traverse and remap nested packs.
/// \{
/// Maps the pack with the given mapper.
///
/// 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<T>(pack)...);
}
/// \}
} // namespace cti
#endif // CONTINUABLE_TRAVERSE_HPP_INCLUDED

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

@ -38,6 +38,11 @@
#include <continuable/continuable-trait.hpp>
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
namespace detail {
/// A function which isn't size adjusted and move only
@ -80,6 +85,7 @@ using promise = typename detail::unique_trait_of<
// TODO sink
// clang-format on
/// \}
} // namespace cti
#endif // CONTINUABLE_TYPES_HPP_INCLUDED