seastar::coroutine::without_preemption_check< T > Struct Template Reference

Detailed Description

template<typename T>
struct seastar::coroutine::without_preemption_check< T >

Wrapper for a future which turns off checking for preemption when awaiting it in a coroutine. If constructed from a future, co_await-ing it will bypass checking if the task quota is depleted, which means that a ready future will be handled immediately.

#include <seastar/core/coroutine.hh>

Inheritance diagram for seastar::coroutine::without_preemption_check< T >:

Public Types
using	value_type = internal::future_stored_type_t< T >
	The data type carried by the future.
using	tuple_type = internal::future_tuple_type_t< value_type >
using	promise_type = promise< T >
	The data type carried by the future.
using	get0_return_type = typename future_state::get0_return_type

Public Member Functions
	without_preemption_check (seastar::future< T > &&f) noexcept
value_type &&	get ()
	gets the value returned by the computation More...
std::exception_ptr	get_exception () noexcept
void	wait () noexcept
bool	available () const noexcept
	Checks whether the future is available. More...
bool	failed () const noexcept
	Checks whether the future has failed. More...
template<typename Func , typename Result = typename internal::future_result<Func, T>::future_type> requires std::invocable<Func, T> || (std::same_as<void, T> && std::invocable<Func>)
Result	then (Func &&func) noexcept
	Schedule a block of code to run when the future is ready. More...
template<typename Func , typename Result = futurize_t<internal::result_of_apply_t<Func, T>>>
requires ::seastar::CanApplyTuple< Func, T > Result	then_unpack (Func &&func) noexcept
	Schedule a block of code to run when the future is ready, unpacking tuples. More...
template<std::invocable< future > Func, typename FuncResult = std::invoke_result_t<Func, future>>
futurize_t< FuncResult >	then_wrapped (Func &&func) &noexcept
	Schedule a block of code to run when the future is ready, allowing for exception handling. More...
template<std::invocable< future && > Func, typename FuncResult = std::invoke_result_t<Func, future&&>>
futurize_t< FuncResult >	then_wrapped (Func &&func) &&noexcept
void	forward_to (promise< T > &&pr) noexcept
	Satisfy some promise object with this future as a result. More...
template<std::invocable Func>
future< T >	finally (Func &&func) noexcept
future	or_terminate () noexcept
	Terminate the program if this future fails. More...
future	discard_result () noexcept
	Discards the value carried by this future. More...
template<typename Func > requires std::is_invocable_r_v<future<T> ,Func, std::exception_ptr> || (std::tuple_size_v<tuple_type> == 0 && std::is_invocable_r_v<void, Func, std::exception_ptr>) || (std::tuple_size_v<tuple_type> == 1 && std::is_invocable_r_v<T, Func, std::exception_ptr>) || (std::tuple_size_v<tuple_type> > 1 && std::is_invocable_r_v<tuple_type ,Func, std::exception_ptr>)
future< T >	handle_exception (Func &&func) noexcept
	Handle the exception carried by this future. More...
template<typename Func >
future< T >	handle_exception_type (Func &&func) noexcept
	Handle the exception of a certain type carried by this future. More...
void	ignore_ready_future () noexcept
	Ignore any result hold by this future. More...

Member Function Documentation

available()

template<typename T >

bool seastar::future< T >::available ( ) const

inlinenoexceptinherited

Checks whether the future is available.

Returns

true if the future has a value, or has failed.

discard_result()

template<typename T >

future seastar::future< T >::discard_result ( )

inlinenoexceptinherited

Discards the value carried by this future.

Converts the future into a no-value future<>, by ignoring any result. Exceptions are propagated unchanged.

failed()

template<typename T >

bool seastar::future< T >::failed ( ) const

inlinenoexceptinherited

Checks whether the future has failed.

Returns

true if the future is available and has failed.

finally()

template<typename T >

template<std::invocable Func>

future< T > seastar::future< T >::finally ( Func &&  func )

inlinenoexceptinherited

Finally continuation for statements that require waiting for the result. I.e. you need to "finally" call a function that returns a possibly unavailable future. The returned future will be "waited for", any exception generated will be propagated, but the return value is ignored. I.e. the original return value (the future upon which you are making this call) will be preserved.

If the original return value or the callback return value is an exceptional future it will be propagated.

If both of them are exceptional - the seastar::nested_exception exception with the callback exception on top and the original future exception nested will be propagated.

forward_to()

template<typename T >

void seastar::future< T >::forward_to ( promise< T > &&  pr )

inlinenoexceptinherited

Satisfy some promise object with this future as a result.

Arranges so that when this future is resolve, it will be used to satisfy an unrelated promise. This is similar to scheduling a continuation that moves the result of this future into the promise (using promise::set_value() or promise::set_exception(), except that it is more efficient.

Parameters

pr	a promise that will be fulfilled with the results of this future.

get()

template<typename T >

value_type && seastar::future< T >::get ( )

inlineinherited

gets the value returned by the computation

Requires that the future be available. If the value was computed successfully, it is returned (as an std::tuple). Otherwise, an exception is thrown.

If get() is called in a seastar::thread context, then it need not be available; instead, the thread will be paused until the future becomes available.

Examples

closeable_test.cc.

handle_exception()

template<typename T >

template<typename Func >
requires std::is_invocable_r_v<future<T> ,Func, std::exception_ptr> || (std::tuple_size_v<tuple_type> == 0 && std::is_invocable_r_v<void, Func, std::exception_ptr>) || (std::tuple_size_v<tuple_type> == 1 && std::is_invocable_r_v<T, Func, std::exception_ptr>) || (std::tuple_size_v<tuple_type> > 1 && std::is_invocable_r_v<tuple_type ,Func, std::exception_ptr>)

future< T > seastar::future< T >::handle_exception ( Func &&  func )

inlinenoexceptinherited

Handle the exception carried by this future.

When the future resolves, if it resolves with an exception, handle_exception(func) replaces the exception with the value returned by func. The exception is passed (as a std::exception_ptr) as a parameter to func; func may return the replacement value immediately (T or std::tuple<T...>) or in the future (future<T...>) and is even allowed to return (or throw) its own exception.

The idiom fut.discard_result().handle_exception(...) can be used to handle an exception (if there is one) without caring about the successful value; Because handle_exception() is used here on a future<>, the handler function does not need to return anything.

handle_exception_type()

template<typename T >

template<typename Func >

future< T > seastar::future< T >::handle_exception_type ( Func &&  func )

inlinenoexceptinherited

Handle the exception of a certain type carried by this future.

When the future resolves, if it resolves with an exception of a type that provided callback receives as a parameter, handle_exception_type(func) replaces the exception with the value returned by func. The exception is passed (by reference) as a parameter to func; func may return the replacement value immediately (T or std::tuple<T...>) or in the future (future<T...>) and is even allowed to return (or throw) its own exception. If exception, that future holds, does not match func parameter type it is propagated as is.

ignore_ready_future()

template<typename T >

void seastar::future< T >::ignore_ready_future ( )

inlinenoexceptinherited

Ignore any result hold by this future.

Ignore any result (value or exception) hold by this future. Use with caution since usually ignoring exception is not what you want

or_terminate()

template<typename T >

future seastar::future< T >::or_terminate ( )

inlinenoexceptinherited

Terminate the program if this future fails.

Terminates the entire program is this future resolves to an exception. Use with caution.

then()

template<typename T >

template<typename Func , typename Result = typename internal::future_result<Func, T>::future_type>
requires std::invocable<Func, T> || (std::same_as<void, T> && std::invocable<Func>)

Result seastar::future< T >::then ( Func &&  func )

inlinenoexceptinherited

Schedule a block of code to run when the future is ready.

Schedules a function (often a lambda) to run when the future becomes available. The function is called with the result of this future's computation as parameters. The return value of the function becomes the return value of then(), itself as a future; this allows then() calls to be chained.

If the future failed, the function is not called, and the exception is propagated into the return value of then().

Parameters

func	- function to be called when the future becomes available, unless it has failed.

Returns

a future representing the return value of func, applied to the eventual value of this future.

then_unpack()

template<typename T >

template<typename Func , typename Result = futurize_t<internal::result_of_apply_t<Func, T>>>

requires ::seastar::CanApplyTuple< Func, T > Result seastar::future< T >::then_unpack ( Func &&  func )

inlinenoexceptinherited

Schedule a block of code to run when the future is ready, unpacking tuples.

Schedules a function (often a lambda) to run when the future becomes available. The function is called with the result of this future's computation as parameters. The return value of the function becomes the return value of then(), itself as a future; this allows then() calls to be chained.

This member function is only available when the payload is std::tuple; The tuple elements are passed as individual arguments to func, which must have the same arity as the tuple.

If the future failed, the function is not called, and the exception is propagated into the return value of then().

Parameters

func	- function to be called when the future becomes available, unless it has failed.

Returns

a future representing the return value of func, applied to the eventual value of this future.

then_wrapped()

template<typename T >

template<std::invocable< future > Func, typename FuncResult = std::invoke_result_t<Func, future>>

futurize_t< FuncResult > seastar::future< T >::then_wrapped ( Func &&  func ) &

inlinenoexceptinherited

Schedule a block of code to run when the future is ready, allowing for exception handling.

Schedules a function (often a lambda) to run when the future becomes available. The function is called with the this future as a parameter; it will be in an available state. The return value of the function becomes the return value of then_wrapped(), itself as a future; this allows then_wrapped() calls to be chained.

Unlike then(), the function will be called for both value and exceptional futures.

Parameters

func	- function to be called when the future becomes available,

Returns

a future representing the return value of func, applied to the eventual value of this future.

wait()

template<typename T >

void seastar::future< T >::wait ( )

inlinenoexceptinherited

Wait for the future to be available (in a seastar::thread)

When called from a seastar::thread, this function blocks the thread until the future is available. Other threads and continuations continue to execute; only the thread is blocked.

---

The documentation for this struct was generated from the following file:

• seastar/core/coroutine.hh