coffee/continuable
1
0
Fork 0
mirror of https://github.com/Naios/continuable.git synced 2025-12-06 08:46:44 +08:00
Code Issues Packages Projects Releases Wiki Activity
continuable/group___base.html
Denis Blank 94dc953ba9 Publish
2023-03-21 21:05:30 +01:00

511 lines
49 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Base module | Continuable</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="m-dark+doxygen.compiled.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="base.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="terminal.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="atom-one-dark.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="theme-color" content="#23373B" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">Continuable <span class="m-thin">4.1.0</span></a>
<div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
<a href="#search" class="m-dox-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
<path d="m6 0c-3.3144 0-6 2.6856-6 6 0 3.3144 2.6856 6 6 6 1.4858 0 2.8463-0.54083 3.8945-1.4355-0.0164 0.33797 0.14734 0.75854 0.5 1.1504l3.2227 3.7891c0.55185 0.6139 1.4517 0.66544 2.002 0.11524 0.55022-0.55022 0.49866-1.4501-0.11524-2.002l-3.7891-3.2246c-0.39184-0.35266-0.81242-0.51469-1.1504-0.5 0.89472-1.0482 1.4355-2.4088 1.4355-3.8945 0-3.3128-2.6856-5.998-6-5.998zm0 1.5625a4.4375 4.4375 0 0 1 4.4375 4.4375 4.4375 4.4375 0 0 1-4.4375 4.4375 4.4375 4.4375 0 0 1-4.4375-4.4375 4.4375 4.4375 0 0 1 4.4375-4.4375z"/>
</svg></a>
<a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
<a id="m-navbar-hide" href="#" title="Hide navigation"></a>
</div>
<div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
<div class="m-row">
<ol class="m-col-t-6 m-col-m-none">
<li>
<a href="tutorial.html">Tutorial</a>
<ol>
<li><a href="tutorial-creating-continuables.html">Creating continuables</a></li>
<li><a href="tutorial-chaining-continuables.html">Chaining continuables</a></li>
<li><a href="tutorial-connecting-continuables.html">Connecting continuables</a></li>
<li><a href="tutorial-transforming-continuables.html">Transforming continuables</a></li>
<li><a href="tutorial-awaiting-continuables.html">Awaiting continuables</a></li>
<li><a href="tutorial-promisify-continuables.html">Promisify functions</a></li>
</ol>
</li>
<li>
<a href="pages.html">Pages</a>
<ol>
<li><a href="installation.html">Installation</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="changelog.html">Changelog</a></li>
</ol>
</li>
<li>
<a href="modules.html">Modules</a>
<ol>
<li><a href="group___base.html" id="m-navbar-current">Base</a></li>
<li><a href="group___connections.html">Connections</a></li>
<li><a href="group___promisify.html">Promisify</a></li>
<li><a href="group___testing.html">Testing</a></li>
<li><a href="group___types.html">Types</a></li>
<li><a href="group___transforms.html">Transforms</a></li>
<li><a href="group___traversal.html">Traversal</a></li>
</ol>
</li>
</ol>
<ol class="m-col-t-6 m-col-m-none" start="4">
<li>
<a href="namespacecti.html">cti</a>
<ol>
<li><a href="namespacecti_1_1transforms.html">cti::transforms</a></li>
<li><a href="classcti_1_1continuable__base.html">cti::continuable_base</a></li>
<li><a href="classcti_1_1promise__base.html">cti::promise_base</a></li>
</ol>
</li>
<li class="m-show-m"><a href="#search" class="m-dox-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
<path d="m6 0c-3.3144 0-6 2.6856-6 6 0 3.3144 2.6856 6 6 6 1.4858 0 2.8463-0.54083 3.8945-1.4355-0.0164 0.33797 0.14734 0.75854 0.5 1.1504l3.2227 3.7891c0.55185 0.6139 1.4517 0.66544 2.002 0.11524 0.55022-0.55022 0.49866-1.4501-0.11524-2.002l-3.7891-3.2246c-0.39184-0.35266-0.81242-0.51469-1.1504-0.5 0.89472-1.0482 1.4355-2.4088 1.4355-3.8945 0-3.3128-2.6856-5.998-6-5.998zm0 1.5625a4.4375 4.4375 0 0 1 4.4375 4.4375 4.4375 4.4375 0 0 1-4.4375 4.4375 4.4375 4.4375 0 0 1-4.4375-4.4375 4.4375 4.4375 0 0 1 4.4375-4.4375z"/>
</svg> Search</a></li>
</ol>
<ol class="m-col-t-6 m-col-m-none">
<li>
<a href="https://github.com/Naios/continuable" aria-label="View source on Github"><i class="fa fa-github"></i> Code</a>
</li>
</ol>
</div>
</div>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
Base <span class="m-thin">module</span></h1>
<p>provides classes and functions to create <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> objects.</p>
<div class="m-block m-default">
<h3>Contents</h3>
<ul>
<li>
Reference
<ul>
<li><a href="#nested-classes">Classes</a></li>
<li><a href="#typedef-members">Typedefs</a></li>
<li><a href="#func-members">Functions</a></li>
</ul>
</li>
</ul>
</div>
<section id="nested-classes">
<h2><a href="#nested-classes">Classes</a></h2>
<dl class="m-dox">
<dt>
<div class="m-dox-template">template&lt;typename Data, typename Annotation&gt;</div>
class <a href="classcti_1_1continuable__base.html" class="m-dox">cti::continuable_base</a>
</dt>
<dd>The main class of the continuable library, it provides the functionality for chaining callbacks and continuations together to a unified hierarchy.</dd>
<dt>
<div class="m-dox-template">template&lt;typename Data, typename Hint&gt;</div>
class <a href="classcti_1_1promise__base.html" class="m-dox">cti::promise_base</a>
</dt>
<dd>The <a href="classcti_1_1promise__base.html" class="m-dox">promise_<wbr />base</a> makes it possible to resolve an asynchronous continuable through it&#x27;s result or through an error type.</dd>
</dl>
</section>
<section id="typedef-members">
<h2><a href="#typedef-members">Typedefs</a></h2>
<dl class="m-dox">
<dt>
<div class="m-dox-template">template&lt;typename T&gt;</div>
using <a href="#gabe4e73c301a2697d9252c400194474e0" class="m-dox">is_continuable</a> = detail::base::is_continuable&lt;T&gt;
</dt>
<dd>Deduces to a true_type if the given type is a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a>.</dd>
</dl>
</section>
<section id="func-members">
<h2><a href="#func-members">Functions</a></h2>
<dl class="m-dox">
<dt>
<div class="m-dox-template">template&lt;typename... Args, typename Continuation&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#gaf47869ea139d88976af5b9654d6d61c0" class="m-dox">make_continuable</a>(</span><span class="m-dox-wrap">Continuation&amp;&amp; continuation) -&gt; auto <span class="m-label m-flat m-primary">constexpr</span></span>
</dt>
<dd>Creates a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> from a promise/callback taking function.</dd>
<dt>
<div class="m-dox-template">template&lt;typename... Args&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#gaa1b6bcf17649b137e29c866ced3569c7" class="m-dox">make_ready_continuable</a>(</span><span class="m-dox-wrap">Args &amp;&amp; ... args) -&gt; auto</span>
</dt>
<dd>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with no result which instantly resolves the promise with no values.</dd>
<dt>
<div class="m-dox-template">template&lt;typename... Args, typename Exception&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#ga41794c321aef916f4fd0fe4c36aa9e6e" class="m-dox">make_exceptional_continuable</a>(</span><span class="m-dox-wrap">Exception&amp;&amp; exception) -&gt; auto <span class="m-label m-flat m-primary">constexpr</span></span>
</dt>
<dd>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with the parameterized result which instantly resolves the promise with the given error type.</dd>
<dt>
<div class="m-dox-template">template&lt;typename... Signature&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#ga7f0646a26ba7ee4ce1ac42caeef3caa1" class="m-dox">make_cancelling_continuable</a>(</span><span class="m-dox-wrap">) -&gt; auto</span>
</dt>
<dd>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with the parameterized result which never resolves its promise and thus cancels the asynchronous continuation chain through throwing a default constructed exception_t.</dd>
<dt>
<div class="m-dox-template">template&lt;typename T&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#gacc7ae86f30e3c0331861ce7871e310dd" class="m-dox">make_plain</a>(</span><span class="m-dox-wrap">T&amp;&amp; value) -&gt; auto</span>
</dt>
<dd>Can be used to disable the special meaning for a returned value in asynchronous handler functions.</dd>
<dt>
<div class="m-dox-template">template&lt;typename... Args&gt;</div>
<span class="m-dox-wrap-bumper">auto <a href="#gacdc6a77a2ff98dabd7a2e9dc8c461934" class="m-dox">recover</a>(</span><span class="m-dox-wrap">Args &amp;&amp; ... args) -&gt; result&lt;detail::traits::unrefcv_t&lt;Args&gt;...&gt;</span>
</dt>
<dd>Can be used to recover to from a failure handler, the result handler which comes after will be called with the corresponding result.</dd>
<dt>
<span class="m-dox-wrap-bumper">auto <a href="#ga9223cf1a04ca2d6950d83d0917192fa5" class="m-dox">rethrow</a>(</span><span class="m-dox-wrap">exception_t exception) -&gt; exceptional_result</span>
</dt>
<dd>Can be used to rethrow an exception to the asynchronous continuation chain, the failure handler which comes after will be called with the corresponding exception.</dd>
<dt>
<span class="m-dox-wrap-bumper">auto <a href="#ga3c1710e55aab586d267f96a02f6cd014" class="m-dox">cancel</a>(</span><span class="m-dox-wrap">) -&gt; cancellation_result</span>
</dt>
<dd>Can be used to cancel an asynchronous continuation chain, the next failure handler which comes after cancel will be called with a default constructed exception_t object.</dd>
<dt>
<span class="m-dox-wrap-bumper">auto <a href="#gac20d32604949856659f84c06ebcaeb9e" class="m-dox">stop</a>(</span><span class="m-dox-wrap">) -&gt; empty_result</span>
</dt>
<dd>Can be used to stop an asynchronous continuation chain, no handler which comes after stop was received won&#x27;t be called.</dd>
</dl>
</section>
<section>
<h2>Typedef documentation</h2>
<section class="m-dox-details" id="gabe4e73c301a2697d9252c400194474e0"><div>
<h3>
<div class="m-dox-template">
template&lt;typename T&gt;
</div>
using <a href="#gabe4e73c301a2697d9252c400194474e0" class="m-dox-self">is_continuable</a> = detail::base::is_continuable&lt;T&gt;
</h3>
<p>Deduces to a true_type if the given type is a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a>.</p>
<aside class="m-note m-default"><h4>Since</h4><p>3.0.0</p></aside>
</div></section>
</section>
<section>
<h2>Function documentation</h2>
<section class="m-dox-details" id="gaf47869ea139d88976af5b9654d6d61c0"><div>
<h3>
<div class="m-dox-template">
template&lt;typename... Args, typename Continuation&gt;
</div>
<span class="m-dox-wrap-bumper">auto </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#gaf47869ea139d88976af5b9654d6d61c0" class="m-dox-self">make_continuable</a>(</span><span class="m-dox-wrap">Continuation&amp;&amp; continuation) <span class="m-label m-primary">constexpr</span></span></span>
</h3>
<p>Creates a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> from a promise/callback taking function.</p>
<table class="m-table m-fullwidth m-flat">
<thead>
<tr><th colspan="2">Template parameters</th></tr>
</thead>
<tbody>
<tr>
<td style="width: 1%">Args</td>
<td><p>The types (signature hint) the given promise is resolved with.</p><ul><li><p><strong>Some arguments</strong> indicate the types the promise will be invoked with.</p><pre class="m-code"><span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="s">&quot;&lt;html&gt;...&lt;/html&gt;&quot;</span><span class="p">);</span>
<span class="p">});</span></pre></li><li><p><code>void</code> <strong>as argument</strong> indicates that the promise will be invoked with no arguments:</p><pre class="m-code"><span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="kt">void</span><span class="o">&gt;</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">();</span>
<span class="p">});</span></pre></li><li><p><strong>No arguments</strong> Since version 3.0.0 make_continuable always requires to be given valid arguments! You should always give the type hint a callback is called with because it&#x27;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.</p><pre class="m-code"><span class="c1">// This won&#39;t work because the arguments are missing:</span>
<span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="sc">&#39;c&#39;</span><span class="p">);</span>
<span class="p">});</span>
<span class="c1">// However, you are allowed to do this:</span>
<span class="n">cti</span><span class="o">::</span><span class="n">continuable</span><span class="o">&lt;</span><span class="kt">float</span><span class="p">,</span> <span class="kt">char</span><span class="o">&gt;</span> <span class="n">ct</span> <span class="o">=</span> <span class="p">[](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="n">callback</span><span class="p">)(</span><span class="mf">0.f</span><span class="p">,</span> <span class="sc">&#39;c&#39;</span><span class="p">);</span>
<span class="p">};</span></pre></li></ul></td>
</tr>
<tr>
<td>Continuation</td>
<td></td>
</tr>
</tbody>
<thead>
<tr><th colspan="2">Parameters</th></tr>
</thead>
<tbody>
<tr>
<td>continuation</td>
<td><p>The continuation the continuable is created from. The continuation must be a callable type accepting a callback parameter which represents the object invokable with the asynchronous result of this continuable.</p><pre class="m-code"><span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="s">&quot;result&quot;</span><span class="p">);</span>
<span class="p">});</span></pre><p>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&#x27;s recommended to accept any callback instead of erasing it.</p><pre class="m-code"><span class="c1">// Good practice:</span>
<span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="s">&quot;result&quot;</span><span class="p">);</span>
<span class="p">});</span>
<span class="c1">// Good practice using a callable object:</span>
<span class="k">struct</span> <span class="n">Continuation</span> <span class="p">{</span>
<span class="k">template</span><span class="o">&lt;</span><span class="k">typename</span> <span class="n">T</span><span class="o">&gt;</span>
<span class="kt">void</span> <span class="k">operator</span><span class="p">()</span> <span class="p">(</span><span class="n">T</span><span class="o">&amp;&amp;</span> <span class="n">continuation</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span><span class="p">(</span><span class="n">Continuation</span><span class="p">{});</span>
<span class="c1">// Bad practice (because of unnecessary type erasure):</span>
<span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_continuable</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span><span class="p">(</span>
<span class="p">[](</span><span class="n">cti</span><span class="o">::</span><span class="n">promise</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span> <span class="n">promise</span><span class="p">)</span> <span class="p">{</span>
<span class="n">promise</span><span class="p">.</span><span class="n">set_value</span><span class="p">(</span><span class="s">&quot;result&quot;</span><span class="p">);</span>
<span class="p">});</span></pre></td>
</tr>
</tbody>
<tfoot>
<tr>
<th>Returns</th>
<td>A <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with unspecified template parameters which wraps the given continuation. In order to convert the <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> to a known type you need to apply type erasure through the <a href="group___types.html#ga95d2328ba27fe194491b52073b58be50" class="m-dox">continuable</a> or <a href="group___types.html#gaaed43cf7309b600464b10fde4a3df0de" class="m-dox">promise</a> facilities.</td>
</tr>
</tfoot>
</table>
<aside class="m-note m-info"><h4>Note</h4><p>You should always turn the callback/promise into a r-value if possible (<code>std::move</code> or <code>std::forward</code>) for qualifier correct invokation. Additionally it&#x27;s important to know that all continuable promises are callbacks and just expose their call operator nicely through <a href="classcti_1_1promise__base.html#a223d666944a70441b3837b461b1094c7" class="m-dox">set_<wbr />value</a> and <a href="classcti_1_1promise__base.html#a449356e97645d44cf4194932cc2006d7" class="m-dox">set_<wbr />exception</a>.</p></aside><aside class="m-note m-default"><h4>Since</h4><p>1.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="gaa1b6bcf17649b137e29c866ced3569c7"><div>
<h3>
<div class="m-dox-template">
template&lt;typename... Args&gt;
</div>
<span class="m-dox-wrap-bumper">auto </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#gaa1b6bcf17649b137e29c866ced3569c7" class="m-dox-self">make_ready_continuable</a>(</span><span class="m-dox-wrap">Args &amp;&amp; ... args)</span></span>
</h3>
<p>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with no result which instantly resolves the promise with no values.</p>
<aside class="m-note m-warning"><h4>Attention</h4><p>Usually using this function isn&#x27;t needed at all since the continuable library is capable of working with plain values in most cases. Try not to use it since it causes unnecessary recursive function calls.</p></aside><aside class="m-note m-default"><h4>Since</h4><p>3.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="ga41794c321aef916f4fd0fe4c36aa9e6e"><div>
<h3>
<div class="m-dox-template">
template&lt;typename... Args, typename Exception&gt;
</div>
<span class="m-dox-wrap-bumper">auto </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#ga41794c321aef916f4fd0fe4c36aa9e6e" class="m-dox-self">make_exceptional_continuable</a>(</span><span class="m-dox-wrap">Exception&amp;&amp; exception) <span class="m-label m-primary">constexpr</span></span></span>
</h3>
<p>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with the parameterized result which instantly resolves the promise with the given error type.</p>
<table class="m-table m-fullwidth m-flat">
<thead>
<tr><th colspan="2">Template parameters</th></tr>
</thead>
<tbody>
<tr>
<td style="width: 1%">Args</td>
<td>The fake signature of the returned continuable.</td>
</tr>
<tr>
<td>Exception</td>
<td></td>
</tr>
</tbody>
</table>
<p>See an example below:</p><pre class="m-code"><span class="n">std</span><span class="o">::</span><span class="n">logic_error</span> <span class="n">exception</span><span class="p">(</span><span class="s">&quot;Some issue!&quot;</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">ptr</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">exception</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">ct</span> <span class="o">=</span> <span class="n">cti</span><span class="o">::</span><span class="n">make_exceptional_continuable</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">(</span><span class="n">ptr</span><span class="p">);</span></pre><aside class="m-note m-default"><h4>Since</h4><p>3.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="ga7f0646a26ba7ee4ce1ac42caeef3caa1"><div>
<h3>
<div class="m-dox-template">
template&lt;typename... Signature&gt;
</div>
<span class="m-dox-wrap-bumper">auto </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#ga7f0646a26ba7ee4ce1ac42caeef3caa1" class="m-dox-self">make_cancelling_continuable</a>(</span><span class="m-dox-wrap">)</span></span>
</h3>
<p>Returns a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> with the parameterized result which never resolves its promise and thus cancels the asynchronous continuation chain through throwing a default constructed exception_t.</p>
<table class="m-table m-fullwidth m-flat">
<thead>
<tr><th colspan="2">Template parameters</th></tr>
</thead>
<tbody>
<tr>
<td style="width: 1%">Signature</td>
<td>The fake signature of the returned continuable.</td>
</tr>
</tbody>
</table>
<p>This can be used to cancel an asynchronous continuation chain when returning a <a href="classcti_1_1continuable__base.html" class="m-dox">continuable_<wbr />base</a> from a handler where other paths could possibly continue the asynchronous chain. See an example below:</p><pre class="m-code"><span class="n">do_sth</span><span class="p">().</span><span class="n">then</span><span class="p">([</span><span class="n">weak</span> <span class="o">=</span> <span class="k">this</span><span class="o">-&gt;</span><span class="n">weak_from_this</span><span class="p">()]()</span> <span class="o">-&gt;</span> <span class="n">continuable</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">me</span> <span class="o">=</span> <span class="n">weak</span><span class="p">.</span><span class="n">lock</span><span class="p">())</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">do_sth_more</span><span class="p">();</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c1">// Abort the asynchronous continuation chain since the</span>
<span class="c1">// weakly referenced object expired previously.</span>
<span class="k">return</span> <span class="n">make_cancelling_continuable</span><span class="o">&lt;</span><span class="kt">void</span><span class="o">&gt;</span><span class="p">();</span>
<span class="p">}</span>
<span class="p">});</span></pre><p>The default unhandled exception handler ignores exception types that don&#x27;t evaluate to true when being converted to a bool. This saves expensive construction of std::exception_ptr or similar types, where only one exception type is used for signaling the cancellation.</p><aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="gacc7ae86f30e3c0331861ce7871e310dd"><div>
<h3>
<div class="m-dox-template">
template&lt;typename T&gt;
</div>
<span class="m-dox-wrap-bumper">auto </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#gacc7ae86f30e3c0331861ce7871e310dd" class="m-dox-self">make_plain</a>(</span><span class="m-dox-wrap">T&amp;&amp; value)</span></span>
</h3>
<p>Can be used to disable the special meaning for a returned value in asynchronous handler functions.</p>
<p>Several types have a special meaning when being returned from a callable passed to asynchronous handler functions like:</p><ul><li><a href="classcti_1_1continuable__base.html#adf02030d7211ffc4610f3bcb13d2a149" class="m-dox">continuable_base::<wbr />then</a></li><li><a href="classcti_1_1continuable__base.html#a7001122101ed32f729e39c53d6cb9c7f" class="m-dox">continuable_base::<wbr />fail</a></li><li><a href="classcti_1_1continuable__base.html#ad4960d0794abb800f1dfd9a668900149" class="m-dox">continuable_base::<wbr />next</a></li></ul><p>For instance such types are std::tuple, std::pair and <a href="classcti_1_1result.html" class="m-dox">cti::<wbr />result</a>.</p><p>Wrapping such an object through a call to make_plain disables the special meaning for such objects as shown below:</p><pre class="m-code"><span class="n">continuable</span><span class="o">&lt;</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">&gt;</span> <span class="n">c</span> <span class="o">=</span> <span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">make_plain</span><span class="p">(</span><span class="n">make_result</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">));</span>
<span class="p">})</span></pre><aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="gacdc6a77a2ff98dabd7a2e9dc8c461934"><div>
<h3>
<div class="m-dox-template">
template&lt;typename... Args&gt;
</div>
<span class="m-dox-wrap-bumper">result&lt;detail::traits::unrefcv_t&lt;Args&gt;...&gt; </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#gacdc6a77a2ff98dabd7a2e9dc8c461934" class="m-dox-self">recover</a>(</span><span class="m-dox-wrap">Args &amp;&amp; ... args)</span></span>
</h3>
<p>Can be used to recover to from a failure handler, the result handler which comes after will be called with the corresponding result.</p>
<p>The <a href="classcti_1_1exceptional__result.html" class="m-dox">exceptional_<wbr />result</a> returned by this function can be returned from any result or failure handler in order to rethrow the exception.</p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">recover</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">recover</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Recovered from the failure</span>
<span class="p">})</span></pre><p>A corresponding <a href="classcti_1_1result.html" class="m-dox">result</a> is returned by <a href="group___base.html#gacdc6a77a2ff98dabd7a2e9dc8c461934" class="m-dox">recover</a></p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">recover</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">recover</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">&gt;</span> <span class="p">{</span>
<span class="c1">// Recovered from the failure</span>
<span class="p">})</span></pre><aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="ga9223cf1a04ca2d6950d83d0917192fa5"><div>
<h3>
<span class="m-dox-wrap-bumper">exceptional_result </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#ga9223cf1a04ca2d6950d83d0917192fa5" class="m-dox-self">rethrow</a>(</span><span class="m-dox-wrap">exception_t exception)</span></span>
</h3>
<p>Can be used to rethrow an exception to the asynchronous continuation chain, the failure handler which comes after will be called with the corresponding exception.</p>
<p>The <a href="classcti_1_1exceptional__result.html" class="m-dox">exceptional_<wbr />result</a> returned by this function can be returned from any result or failure handler in order to rethrow the exception.</p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">next</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span><span class="p">...)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">});</span></pre><p>The returned <a href="classcti_1_1exceptional__result.html" class="m-dox">exceptional_<wbr />result</a> is convertible to any <a href="classcti_1_1result.html" class="m-dox">result</a> as shown below:</p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">next</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span><span class="p">...)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">rethrow</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_exception_ptr</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="p">{}));</span>
<span class="p">});</span></pre><aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="ga3c1710e55aab586d267f96a02f6cd014"><div>
<h3>
<span class="m-dox-wrap-bumper">cancellation_result </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#ga3c1710e55aab586d267f96a02f6cd014" class="m-dox-self">cancel</a>(</span><span class="m-dox-wrap">)</span></span>
</h3>
<p>Can be used to cancel an asynchronous continuation chain, the next failure handler which comes after cancel will be called with a default constructed exception_t object.</p>
<p>The <a href="structcti_1_1cancellation__result.html" class="m-dox">cancellation_<wbr />result</a> returned by this function can be returned from any result or failure handler in order to cancel the chain.</p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">next</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span><span class="p">...)</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">});</span></pre><p>The returned <a href="structcti_1_1empty__result.html" class="m-dox">empty_<wbr />result</a> is convertible to any <a href="classcti_1_1result.html" class="m-dox">result</a> as shown below:</p><pre class="m-code"><span class="n">http_request</span><span class="p">(</span><span class="s">&quot;example.com&quot;</span><span class="p">)</span>
<span class="p">.</span><span class="n">then</span><span class="p">([](</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">content</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">fail</span><span class="p">([](</span><span class="n">cti</span><span class="o">::</span><span class="n">exception_t</span> <span class="n">exception</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">})</span>
<span class="p">.</span><span class="n">next</span><span class="p">([](</span><span class="k">auto</span><span class="o">&amp;&amp;</span><span class="p">...)</span> <span class="o">-&gt;</span> <span class="n">cti</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;&gt;</span> <span class="p">{</span>
<span class="k">return</span> <span class="n">cancel</span><span class="p">();</span>
<span class="p">});</span></pre><aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
<section class="m-dox-details" id="gac20d32604949856659f84c06ebcaeb9e"><div>
<h3>
<span class="m-dox-wrap-bumper">empty_result </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#gac20d32604949856659f84c06ebcaeb9e" class="m-dox-self">stop</a>(</span><span class="m-dox-wrap">)</span></span>
</h3>
<p>Can be used to stop an asynchronous continuation chain, no handler which comes after stop was received won&#x27;t be called.</p>
<aside class="m-note m-default"><h4>Since</h4><p>4.0.0</p></aside>
</div></section>
</section>
</div>
</div>
</div>
</article></main>
<div class="m-dox-search" id="search">
<a href="#!" onclick="return hideSearch()"></a>
<div class="m-container">
<div class="m-row">
<div class="m-col-m-8 m-push-m-2">
<div class="m-dox-search-header m-text m-small">
<div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
<div id="search-symbolcount">&hellip;</div>
</div>
<div class="m-dox-search-content">
<form>
<input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
</form>
<noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
<div id="search-help" class="m-text m-dim m-text-center">
<p class="m-noindent">Search for symbols, directories, files, pages or
modules. You can omit any prefix from the symbol or file path; adding a
<code>:</code> or <code>/</code> suffix lists all members of given symbol or
directory.</p>
<p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
/ <span class="m-label m-dim">&uarr;</span> to navigate through the list,
<span class="m-label m-dim">Enter</span> to go.
<span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
copy a link to the result using <span class="m-label m-dim">⌘</span>
<span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
<span class="m-label m-dim">M</span> produces a Markdown link.</p>
</div>
<div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
<ul id="search-results"></ul>
</div>
</div>
</div>
</div>
</div>
<script src="search.js"></script>
<script src="searchdata.js" async="async"></script>
<footer><nav>
<div class="m-container">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<b><a
href="https://github.com/Naios/continuable">continuable</a></b>
-
C++14
allocation
aware
futures</br>Copyright
2015&ndash;2020
<a
href="https://github.com/Naios">Denis
Blank</a>.
Contact
the
author
via
<a
href="mailto:denis.blank@outlook.com">e-mail</a>.</br>Powered
by
<a
href="http://doxygen.org/">Doxygen</a>
and
<a
href="http://mcss.mosra.cz/">m.css</a>
</div>
</div>
</div>
</nav></footer>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink