diff --git a/doc/installation.dox b/doc/installation.dox new file mode 100644 index 0000000..ad65d37 --- /dev/null +++ b/doc/installation.dox @@ -0,0 +1,30 @@ +/* + 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 installation Installation +\brief An explanation on how to install continuable on various platforms. + +\tableofcontents + +*/ +} diff --git a/doc/tutorial-chaining-continuables.dox b/doc/tutorial-chaining-continuables.dox index 83c7257..c95c9c7 100644 --- a/doc/tutorial-chaining-continuables.dox +++ b/doc/tutorial-chaining-continuables.dox @@ -63,13 +63,17 @@ mysql_query("SELECT `id`, `name` FROM `users`") // ^^^^ Templated callbacks are possible too }) // ... you may even pass continuables to the `then` method directly: - .then(mysql_query("SELECT * `statistics`")) + .then(mysql_query("SELECT * FROM `statistics`")) .then([](ResultSet result) { // ... }); \endcode -\section tutorial-chaining-continuables-fail Using fail and errors +\section tutorial-chaining-continuables-fail Using fail and exceptions + +Asynchronous exceptions are supported too. Exceptions that were set through +\ref promise_base::set_exception are forwarded to the first available registered +handler that was attached through \ref continuable_base::fail : \code{.cpp} http_request("github.com") @@ -85,6 +89,36 @@ http_request("github.com") }); \endcode +Multiple handlers are allowed to be registered, however the asynchronous call +hierarchy is aborted after the first called fail handler and only the closest +handler below is called. + +\note Retrieving a `std::exception_ptr` from a current exception + may be done as shown below: + \code{.cpp} + auto do_sth() { + return cti::make_continuable([=] (auto&& promise) { + try { + // Usually the exception is thrown by another expression + throw std::exception{}; + } catch(...) { + promise.set_exception(std::current_exception()); + } + }); + } + \endcode + +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 +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. + When exceptions are disabled this definition is set automatically. +- `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`: Define this to use a user defined + error type. + \section tutorial-chaining-continuables-next Using next for everything diff --git a/doc/tutorial-creating-continuables.dox b/doc/tutorial-creating-continuables.dox index 95ce021..7f0b81d 100644 --- a/doc/tutorial-creating-continuables.dox +++ b/doc/tutorial-creating-continuables.dox @@ -40,7 +40,10 @@ The library provides \ref make_ready_continuable which may be used to create a \ref continuable_base from an arbitrary amount of values: \code{.cpp} -cti::continuable c = cti::make_ready_continuable(0); +auto one = cti::make_ready_continuable(0); + +cti::continuable three = + cti::make_ready_continuable(0, 1.f, '2'); \endcode \note In most situations you will never use \ref make_ready_continuable @@ -79,6 +82,28 @@ auto http_request(std::string url) { } \endcode +An alternative would be a \ref continuable_base with a result of zero arguments: + +\code{.cpp} +auto wait_for(std::chrono::milliseconds duration) { + return cti::make_continuable([](auto&& promise) { + // ^^^^ + + // Resolve the promise later when the duration is over + promise.set_value(); +}); +\endcode + +A \ref continuable_base may resolve with an arbitrary count of result values: + +\code{.cpp} +auto resolve_sth() { + return cti::make_continuable( + [](auto&& promise) { + promise.set_value(0, 1, 2.f, '3'); + }); +\endcode + \warning A \ref promise_base is only usable once and thus invalidated after it was resolved!