From f6ee04a0c0e4ed06882f8ae8d02944d8c6894978 Mon Sep 17 00:00:00 2001 From: Denis Blank Date: Sat, 10 Mar 2018 14:28:46 +0100 Subject: [PATCH] Add a configuration documentation section --- CMakeLists.txt | 2 +- doc/configuration.dox | 39 +++++++++++++++++++ doc/tutorial-chaining-continuables.dox | 49 +++++++++++++++++------- include/continuable/continuable-base.hpp | 4 +- include/continuable/detail/base.hpp | 6 +-- include/continuable/detail/features.hpp | 7 ++++ 6 files changed, 88 insertions(+), 19 deletions(-) create mode 100644 doc/configuration.dox diff --git a/CMakeLists.txt b/CMakeLists.txt index 277a6e8..1584fa5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -85,7 +85,7 @@ if (CTI_CONTINUABLE_WITH_AWAIT) target_compile_definitions(continuable-base INTERFACE - -DCONTINUABLE_HAS_EXPERIMENTAL_COROUTINE) + -DCONTINUABLE_WITH_EXPERIMENTAL_COROUTINE) endif() add_library(continuable INTERFACE) diff --git a/doc/configuration.dox b/doc/configuration.dox new file mode 100644 index 0000000..b57a79b --- /dev/null +++ b/doc/configuration.dox @@ -0,0 +1,39 @@ +/* + Copyright(c) 2015 - 2018 Denis Blank + + 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 configuration Configuration +\brief Covers optional preprocessor macros that change the libraries behaviour + +By default the library doesn't require any preprocessor definitions +to be defined in order to work. However it is possible to define some +in order to change the libraries behaviour: + +| Preprocessor definition | Consequence | +| ----------------------------------------- | --------------- | +| `CONTINUABLE_WITH_NO_EXCEPTIONS` | Exceptions are disabled and `std::error_condition` is used as \ref error_type . See \ref tutorial-chaining-continuables-fail for details. | +| `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE` | Exceptions are disabled and the type defined by `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE` is used as \ref error_type . See \ref tutorial-chaining-continuables-fail for details. | +| `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS` | Allows unhandled exceptions in asynchronous call hierarchies. See \ref tutorial-chaining-continuables-fail for details. | +| `CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE` | Enables support for experimental coroutines and `co_await` expressions. | + +*/ +} diff --git a/doc/tutorial-chaining-continuables.dox b/doc/tutorial-chaining-continuables.dox index c95c9c7..dbb59f3 100644 --- a/doc/tutorial-chaining-continuables.dox +++ b/doc/tutorial-chaining-continuables.dox @@ -78,7 +78,7 @@ handler that was attached through \ref continuable_base::fail : \code{.cpp} http_request("github.com") .then([] (std::string result) { - // Is never called + // Is never called if an error occurs }) .fail([] (std::exception_ptr ptr) { try { @@ -111,29 +111,52 @@ handler below is called. Continuable also supports error codes automatically if exceptions are disabled. Additionally it is possible to specify a custom error type through defining. -The \ref cti::error_type will be `std::exception_ptr` except if any of the +\code{.cpp} +http_request("github.com") + .then([] (std::string result) { + // Is never called if an error occurs + }) + .fail([] (std::error_condition error) { + error.value(); + error.category(); + }); +\endcode + +The \ref error_type will be `std::exception_ptr` except if any of the following definitions is defined: - `CONTINUABLE_WITH_NO_EXCEPTIONS`: Define this to use `std::error_condition` - as \ref cti::error_type and to disable exception support. + as \ref error_type and to disable exception support. When exceptions are disabled this definition is set automatically. - `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`: Define this to use a user defined error type. +\attention By default unhandled exceptions or errors will trigger + a built-in trap that causes abnormal application shutdown. + In order to prevent this and to allow unhandled errors + define `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS`. + \section tutorial-chaining-continuables-next Using next for everything +Sometimes it's required to provide a continuation and error handler from the +same object. In order to avoid overloading conflicts there is the special +method \ref continuable_base::next provided. +The exception path overload is marked through the \ref dispatch_error_tag : -The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify +\code{.cpp} +struct handle_everything { + void operator() (std::string result) { + // ... + } + void operator() (cti::dispatch_error_tag, cti::error_type) { + // ... + } +}; -- Continue the continuation using `.then(...)` and `.fail(...)`, exceptions are passed to the first available handler: +// ... - \endcode +http_request("github.com") + .next(handle_everything{}); +\endcode -- Create connections between the continuables and use its compound result: - \code{.cpp} - (http_request("github.com") && (http_request("travis-ci.org") || http_request("atom.io"))) - .then([](std::string github, std::string travis_or_atom) { - // The promise is called with the response of github and travis or atom. - }); - \endcode */ } diff --git a/include/continuable/continuable-base.hpp b/include/continuable/continuable-base.hpp index 6c39626..c0c4978 100644 --- a/include/continuable/continuable-base.hpp +++ b/include/continuable/continuable-base.hpp @@ -73,7 +73,7 @@ namespace cti { /// \note see continuable::next for details. /// /// \since 2.0.0 -using detail::types::dispatch_error_tag; +using dispatch_error_tag = detail::types::dispatch_error_tag; /// Represents the type that is used as error type /// @@ -84,7 +84,7 @@ using detail::types::dispatch_error_tag; /// defining `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`. /// /// \since 2.0.0 -using detail::types::error_type; +using error_type = detail::types::error_type; /// Deduces to a true_type if the given type is a continuable_base. /// diff --git a/include/continuable/detail/base.hpp b/include/continuable/detail/base.hpp index e717a7a..235baeb 100644 --- a/include/continuable/detail/base.hpp +++ b/include/continuable/detail/base.hpp @@ -457,12 +457,12 @@ struct final_callback : util::non_copyable { void operator()(types::dispatch_error_tag, types::error_type error) && { (void)error; -#ifndef CONTINUABLE_WITH_UNHANDLED_ERRORS +#ifndef CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS // There were unhandled errors inside the asynchronous call chain! - // Define `CONTINUABLE_WITH_UNHANDLED_ERRORS` in order + // Define `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS` in order // to ignore unhandled errors!" util::trap(); -#endif // CONTINUABLE_WITH_UNHANDLED_ERRORS +#endif // CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS } template diff --git a/include/continuable/detail/features.hpp b/include/continuable/detail/features.hpp index 5fd0a22..e59408e 100644 --- a/include/continuable/detail/features.hpp +++ b/include/continuable/detail/features.hpp @@ -83,6 +83,13 @@ #define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE #endif +/// Define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE when +/// CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE is defined. +#if !defined(CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE) && \ + defined(CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE) + #define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE +#endif + /// Define CONTINUABLE_HAS_EXCEPTIONS when exceptions are used #if !defined(CONTINUABLE_WITH_CUSTOM_ERROR_TYPE) && \ !defined(CONTINUABLE_WITH_NO_EXCEPTIONS)