cuda::experimental::stf::on_throw#

template<class _Reaction>
auto cuda::experimental::stf::on_throw(
_Reaction &&__reaction,
const ::cuda::std::source_location __loc = ::cuda::std::source_location::current()
) noexcept#

Creates a policy saying how to react if a callable throws.

Apply the policy with on_throw(policy) << callable. Its expression type is always decltype(callable()); no policy changes it.

A policy is an object exposing any of two optional capabilities, discovered by compile-time introspection: the exception hook (const std::exception*, source_location, Fn&) whose return value is its answer on the throw path (the callable may be re-invoked by policies like retry; most policies ignore it), and a success hook on_success(...) that observes the result while preserving its type. The named policies include notify, subst, defer, rethrow, retry, as_expected, noop, exception_policies::catch_only, exception_policies::catch_exactly, when, translate / exception_policies::nest, delay, exception_policies::backoff, and remember, circuit_breaker, and exception_policies::always. Guards decline what they do not claim; translators decline with a different exception; delay/backoff/retry re-run; remember serves the last success. Policies compose with & (sequence; the last element answers; non-final answers are discarded) and | (alternation; the left may decline by throwing), and with * (n-fold |).

For backward compatibility on_throw also accepts non-policy reactions: std::ignore resumes with a default-constructed result; and anything else is taken as a substitution value, exactly as subst(value) (including a user’s nullary nullval-returning ending, which dies silently &#8212; pair with notify & to opt the report back in). A substitution passed as an lvalue can serve a reference result, which the policy refers to rather than copies:

int fallback = 42;
int& x = on_throw(fallback) << [] { return returns_a_reference(); }; // x is fallback on a throw

The callable itself must not be noexcept: an exception raised inside one ends the program where it stands, leaving the policy unreachable, so such a pairing is rejected instead of standing there looking like protection. Call such a callable directly.

The location defaults to the call site; pass one explicitly to report a different site.

Vocabulary visibility: the named policies live in the non-inline namespace exception_policies. Blessed patterns are a block-scope using namespace cuda::experimental::stf::exception_policies; at the function that configures sinks, or a namespace alias (namespace pol = cuda::experimental::stf::exception_policies;):

using namespace cuda::experimental::stf::exception_policies;
on_throw(notify & retry * 3 | subst(-1)) << flaky;

namespace pol = cuda::experimental::stf::exception_policies;
on_throw(pol::subst(0)) << flaky;

Note

When querying noexcept(on_throw(policy) << f) in a constant expression, pass a location explicitly: nvcc’s front-end with a gcc host reports the defaulted source_location::current() argument as potentially throwing, tainting the query (the call itself is noexcept either way).

Parameters:

  • __reaction – [in] The policy (or a reaction normalized into one), owned if passed an rvalue and referred to if passed an lvalue.

  • __loc – [in] The location passed to exception hooks.

Returns:

A policy object consumed by operator<<.

On this page