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

A co_await-able object handling an API call in parallel with the caller. More...

#include <coro/async.h>

+ Inheritance diagram for dpp::async< R >:
+ Collaboration diagram for dpp::async< R >:

Public Types

using result_type = R
 The return type of the API call. Defaults to confirmation_callback_t. More...
 

Public Member Functions

template<typename Obj , typename Fun , typename... Args>
 async (Obj &&obj, Fun &&fun, Args &&... args)
 Construct an async object wrapping an object method, the call is made immediately by forwarding to std::invoke and can be awaited later to retrieve the result. More...
 
template<typename Fun , typename... Args>
 async (Fun &&fun, Args &&... args)
 Construct an async object wrapping an invokeable object, the call is made immediately by forwarding to std::invoke and can be awaited later to retrieve the result. More...
 
 async (const async &)=delete
 Copy constructor is disabled. More...
 
 async (async &&)=default
 Move constructor, moves the awaitable async object. More...
 
asyncoperator= (const async &)=delete
 Copy assignment operator is disabled. More...
 
asyncoperator= (async &&)=default
 Move assignment operator, moves the awaitable async object. More...
 
 ~async ()
 Destructor, signals to the callback that the async object is gone and shouldn't be notified of the result. More...
 
void if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime ()
 Title :) 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...
 
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< R >
 
using state_flags = detail::promise::state_flags
 

Protected Member Functions

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
 Non-owning pointer to the promise, which must be kept alive for the entire lifetime of the awaitable. More...
 

Detailed Description

template<typename R>
class dpp::async< R >

A co_await-able object handling an API call in parallel with the caller.

This class is the return type of the dpp::cluster::co_* methods, but it can also be created manually to wrap any async call.

Remarks
- The coroutine may be resumed in another thread, do not rely on thread_local variables.
Warning
- This feature is EXPERIMENTAL. The API may change at any time and there may be bugs. Please report any to GitHub issues or to the D++ Discord server.
Template Parameters
RThe return type of the API call. Defaults to confirmation_callback_t

Member Typedef Documentation

◆ result_type

template<typename R >
using dpp::async< R >::result_type = R

The return type of the API call. Defaults to confirmation_callback_t.

◆ shared_state

using dpp::awaitable< R >::shared_state = detail::promise::promise_base<R >
protectedinherited

◆ state_flags

using dpp::awaitable< R >::state_flags = detail::promise::state_flags
protectedinherited

Constructor & Destructor Documentation

◆ async() [1/4]

template<typename R >
template<typename Obj , typename Fun , typename... Args>
dpp::async< R >::async ( Obj &&  obj,
Fun &&  fun,
Args &&...  args 
)
inlineexplicit

Construct an async object wrapping an object method, the call is made immediately by forwarding to std::invoke and can be awaited later to retrieve the result.

Parameters
objThe object to call the method on
funThe method of the object to call. Its last parameter must be a callback taking a parameter of type R
argsParameters to pass to the method, excluding the callback

◆ async() [2/4]

template<typename R >
template<typename Fun , typename... Args>
dpp::async< R >::async ( Fun &&  fun,
Args &&...  args 
)
inlineexplicit

Construct an async object wrapping an invokeable object, the call is made immediately by forwarding to std::invoke and can be awaited later to retrieve the result.

Parameters
funThe object to call using std::invoke. Its last parameter must be a callable taking a parameter of type R
argsParameters to pass to the object, excluding the callback

◆ async() [3/4]

template<typename R >
dpp::async< R >::async ( const async< R > &  )
delete

Copy constructor is disabled.

◆ async() [4/4]

template<typename R >
dpp::async< R >::async ( async< R > &&  )
default

Move constructor, moves the awaitable async object.

◆ ~async()

template<typename R >
dpp::async< R >::~async ( )
inline

Destructor, signals to the callback that the async object is gone and shouldn't be notified of the result.

Member Function Documentation

◆ abandon()

auto dpp::awaitable< R >::abandon
protectedinherited

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()

bool dpp::awaitable< R >::await_ready
inherited

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()

void dpp::awaitable< R >::if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime ( )
inlineinherited

Title :)

We use this in the destructor

◆ operator=() [1/2]

template<typename R >
async & dpp::async< R >::operator= ( async< R > &&  )
default

Move assignment operator, moves the awaitable async object.

◆ operator=() [2/2]

template<typename R >
async & dpp::async< R >::operator= ( const async< R > &  )
delete

Copy assignment operator is disabled.

◆ sync_wait()

auto dpp::basic_awaitable< awaitable< R > >::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< R > >::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< R > >::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< R > >::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()

bool dpp::awaitable< R >::valid
noexceptinherited

Check whether this awaitable refers to a valid promise.

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

Member Data Documentation

◆ state_ptr

shared_state* dpp::awaitable< R >::state_ptr
protectedinherited

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

D++ Library version 10.0.31D++ Library version 10.0.30D++ Library version 10.0.29D++ Library version 10.0.28D++ Library version 10.0.27D++ Library version 10.0.26D++ Library version 10.0.25D++ Library version 10.0.24D++ Library version 10.0.23D++ Library version 10.0.22D++ Library version 10.0.21D++ Library version 10.0.20D++ Library version 10.0.19D++ Library version 10.0.18D++ Library version 10.0.17D++ Library version 10.0.16D++ Library version 10.0.15D++ Library version 10.0.14D++ Library version 10.0.13D++ Library version 10.0.12D++ Library version 10.0.11D++ Library version 10.0.10D++ Library version 10.0.9D++ Library version 10.0.8D++ Library version 10.0.7D++ Library version 10.0.6D++ Library version 10.0.5D++ Library version 10.0.4D++ Library version 10.0.3D++ Library version 10.0.2D++ Library version 10.0.1D++ Library version 10.0.0D++ Library version 9.0.19D++ Library version 9.0.18D++ Library version 9.0.17D++ Library version 9.0.16D++ Library version 9.0.15D++ Library version 9.0.14D++ 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