D++ (DPP)
C++ Discord API Bot Library
dpp::awaitable< T > Class Template Reference

Generic awaitable class, represents a future value that can be co_await-ed on. More...

+ Inheritance diagram for dpp::awaitable< T >:
+ Collaboration diagram for dpp::awaitable< T >:

Classes

struct  awaiter
 Awaiter returned by co_await. More...
 

Public Member Functions

 awaitable ()=default
 Construct an empty awaitable. More...
 
 awaitable (const awaitable &)=delete
 Copy construction is disabled. More...
 
 awaitable (awaitable &&rhs) noexcept
 Move from another awaitable. More...
 
void if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime ()
 Title :) More...
 
 ~awaitable ()
 Destructor. More...
 
awaitableoperator= (const awaitable &)=delete
 Copy assignment is disabled. More...
 
awaitableoperator= (awaitable &&rhs) noexcept
 Move from another awaitable. More...
 
bool valid () const noexcept
 Check whether this awaitable refers to a valid promise. More...
 
bool await_ready () const
 Check whether or not co_await-ing this would suspend the caller, i.e. if we have the result or not. More...
 
template<typename Derived >
 requires (std::is_base_of_v< awaitable, std::remove_cv_t< Derived >>) friend awaiter< Derived & > operator co_await(Derived &obj) noexcept
 Overload of the co_await operator. More...
 
template<typename Derived >
 requires (std::is_base_of_v< awaitable, std::remove_cv_t< Derived >>) friend awaiter< Derived && > operator co_await(Derived &&obj) noexcept
 Overload of the co_await operator. Returns an awaiter referencing this awaitable. More...
 
auto sync_wait ()
 Blocks this thread and waits for the awaitable to finish. More...
 
auto sync_wait_for (const std::chrono::duration< Rep, Period > &duration)
 Blocks this thread and waits for the awaitable to finish. More...
 
auto sync_wait_until (const std::chrono::time_point< Clock, Duration > &time)
 Blocks this thread and waits for the awaitable to finish. More...
 

Protected Types

using shared_state = detail::promise::promise_base< T >
 
using state_flags = detail::promise::state_flags
 
using result_type = T
 The type of the result produced by this task. More...
 

Protected Member Functions

 awaitable (shared_state *promise) noexcept
 Construct from a promise. More...
 
uint8_t abandon ()
 Abandons the promise. More...
 
auto sync_wait_impl (auto &&do_wait)
 Implementation for sync_wait. This is code used by sync_wait, sync_wait_for, sync_wait_until. More...
 

Protected Attributes

shared_statestate_ptr = nullptr
 Non-owning pointer to the promise, which must be kept alive for the entire lifetime of the awaitable. More...
 

Friends

class detail::promise::promise_base< T >
 

Detailed Description

template<typename T>
class dpp::awaitable< T >

Generic awaitable class, represents a future value that can be co_await-ed on.

Roughly equivalent of std::future for coroutines, with the crucial distinction that the future does not own a reference to a "shared state". It holds a non-owning reference to the promise, which must be kept alive for the entire lifetime of the awaitable.

Template Parameters
TType of the asynchronous value
See also
promise

Member Typedef Documentation

◆ result_type

template<typename T >
using dpp::awaitable< T >::result_type = T
protected

The type of the result produced by this task.

◆ shared_state

template<typename T >
using dpp::awaitable< T >::shared_state = detail::promise::promise_base<T>
protected

◆ state_flags

template<typename T >
using dpp::awaitable< T >::state_flags = detail::promise::state_flags
protected

Constructor & Destructor Documentation

◆ awaitable() [1/4]

template<typename T >
dpp::awaitable< T >::awaitable ( shared_state promise)
inlineprotectednoexcept

Construct from a promise.

Parameters
promiseThe promise to refer to.

◆ awaitable() [2/4]

template<typename T >
dpp::awaitable< T >::awaitable ( )
default

Construct an empty awaitable.

Such an awaitable must be assigned a promise before it can be awaited.

◆ awaitable() [3/4]

template<typename T >
dpp::awaitable< T >::awaitable ( const awaitable< T > &  )
delete

Copy construction is disabled.

◆ awaitable() [4/4]

template<typename T >
dpp::awaitable< T >::awaitable ( awaitable< T > &&  rhs)
inlinenoexcept

Move from another awaitable.

Parameters
rhsThe awaitable to move from, left in an unspecified state after this.

◆ ~awaitable()

template<typename T >
dpp::awaitable< T >::~awaitable

Destructor.

May signal to the promise that it was destroyed.

Member Function Documentation

◆ abandon()

template<typename T >
auto dpp::awaitable< T >::abandon
protected

Abandons the promise.

Set the promise's state to broken and unlinks this awaitable.

Returns
uint8_t Flags previously held before setting them to broken

◆ await_ready()

template<typename T >
bool dpp::awaitable< T >::await_ready

Check whether or not co_await-ing this would suspend the caller, i.e. if we have the result or not.

Returns
bool Whether we already have the result or not

◆ if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime()

template<typename T >
void dpp::awaitable< T >::if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime ( )
inline

Title :)

We use this in the destructor

◆ operator=() [1/2]

template<typename T >
awaitable& dpp::awaitable< T >::operator= ( awaitable< T > &&  rhs)
inlinenoexcept

Move from another awaitable.

Parameters
rhsThe awaitable to move from, left in an unspecified state after this.
Returns
*this

◆ operator=() [2/2]

template<typename T >
awaitable& dpp::awaitable< T >::operator= ( const awaitable< T > &  )
delete

Copy assignment is disabled.

◆ requires() [1/2]

template<typename T >
template<typename Derived >
dpp::awaitable< T >::requires ( std::is_base_of_v< awaitable< T >, std::remove_cv_t< Derived >>  ) &
inlinenoexcept

Overload of the co_await operator.

Returns
Returns an awaiter referencing this awaitable.

◆ requires() [2/2]

template<typename T >
template<typename Derived >
dpp::awaitable< T >::requires ( std::is_base_of_v< awaitable< T >, std::remove_cv_t< Derived >>  ) &&
inlinenoexcept

Overload of the co_await operator. Returns an awaiter referencing this awaitable.

Returns
Returns an awaiter referencing this awaitable.

◆ sync_wait()

auto dpp::basic_awaitable< awaitable< T > >::sync_wait
inlineinherited

Blocks this thread and waits for the awaitable to finish.

Attention
This will BLOCK THE THREAD. It is likely you want to use co_await instead.
Returns
If T is void, returns a boolean for which true means the awaitable completed, false means it timed out.
If T is non-void, returns a std::optional<T> for which an absence of value means timed out.

◆ sync_wait_for()

auto dpp::basic_awaitable< awaitable< T > >::sync_wait_for ( const std::chrono::duration< Rep, Period > &  duration)
inlineinherited

Blocks this thread and waits for the awaitable to finish.

Attention
This will BLOCK THE THREAD. It is likely you want to use co_await instead.
Parameters
durationMaximum duration to wait for
Returns
If T is void, returns a boolean for which true means the awaitable completed, false means it timed out.
If T is non-void, returns a std::optional<T> for which an absence of value means timed out.

◆ sync_wait_impl()

auto dpp::basic_awaitable< awaitable< T > >::sync_wait_impl ( auto &&  do_wait)
inlineprotectedinherited

Implementation for sync_wait. This is code used by sync_wait, sync_wait_for, sync_wait_until.

Template Parameters
TimedWhether the wait function times out or not
Parameters
do_waitFunction to do the actual wait on the cv
Returns
If T is void, returns a boolean for which true means the awaitable completed, false means it timed out.
If T is non-void, returns a std::optional<T> for which an absence of value means timed out.

◆ sync_wait_until()

auto dpp::basic_awaitable< awaitable< T > >::sync_wait_until ( const std::chrono::time_point< Clock, Duration > &  time)
inlineinherited

Blocks this thread and waits for the awaitable to finish.

Attention
This will BLOCK THE THREAD. It is likely you want to use co_await instead.
Parameters
timeMaximum time point to wait for
Returns
If T is void, returns a boolean for which true means the awaitable completed, false means it timed out.
If T is non-void, returns a std::optional<T> for which an absence of value means timed out.

◆ valid()

template<typename T >
bool dpp::awaitable< T >::valid
noexcept

Check whether this awaitable refers to a valid promise.

Returns
bool Whether this awaitable refers to a valid promise or not

Friends And Related Function Documentation

◆ detail::promise::promise_base< T >

template<typename T >
friend class detail::promise::promise_base< T >
friend

Member Data Documentation

◆ state_ptr

template<typename T >
shared_state* dpp::awaitable< T >::state_ptr = nullptr
protected

Non-owning pointer to the promise, which must be kept alive for the entire lifetime of the awaitable.

D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0