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...

+ 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 () noexcept
 Construct an empty async. Using co_await on an empty async is undefined behavior. More...
 
 ~async ()
 Destructor. If any callback is pending it will be aborted. More...
 
 async (const async &)
 Copy constructor is disabled. More...
 
 async (async &&other) noexcept=default
 Move constructor. More...
 
asyncoperator= (const async &)=delete
 Copy assignment is disabled. More...
 
asyncoperator= (async &&other) noexcept=default
 Move assignment operator. More...
 
bool await_ready () const noexcept
 Check whether or not co_await-ing this would suspend the caller, i.e. if we have the result or not. More...
 
auto & operator co_await () &noexcept
 Suspend the caller until the request completes. More...
 
const auto & operator co_await () const &noexcept
 Suspend the caller until the request completes. More...
 
auto && operator co_await () &&noexcept
 Suspend the caller until the request completes. More...
 

Friends

class detail::async::async_base< R >
 Internal use only base class. It serves to prevent await_suspend and await_resume from being used directly. 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.

Constructor & Destructor Documentation

◆ async() [1/5]

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/5]

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/5]

template<typename R >
dpp::async< R >::async ( )
noexcept

Construct an empty async. Using co_await on an empty async is undefined behavior.

◆ ~async()

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

Destructor. If any callback is pending it will be aborted.

◆ async() [4/5]

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

Copy constructor is disabled.

◆ async() [5/5]

template<typename R >
dpp::async< R >::async ( async< R > &&  other)
defaultnoexcept

Move constructor.

NOTE: Despite being marked noexcept, this function uses std::lock_guard which may throw. The implementation assumes this can never happen, hence noexcept. Report it if it does, as that would be a bug.

Remarks
Using the moved-from async after this function is undefined behavior.
Parameters
otherThe async object to move the data from.

Member Function Documentation

◆ await_ready()

template<typename R >
bool dpp::async< R >::await_ready ( ) const
noexcept

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 of the API call or not

◆ operator co_await() [1/3]

template<typename R >
auto&& dpp::async< R >::operator co_await ( ) &&
inlinenoexcept

Suspend the caller until the request completes.

Returns
On resumption, this expression evaluates to the result object of type R, as an rvalue reference.

◆ operator co_await() [2/3]

template<typename R >
auto& dpp::async< R >::operator co_await ( ) &
inlinenoexcept

Suspend the caller until the request completes.

Returns
On resumption, this expression evaluates to the result object of type R, as a reference.

◆ operator co_await() [3/3]

template<typename R >
const auto& dpp::async< R >::operator co_await ( ) const &
inlinenoexcept

Suspend the caller until the request completes.

Returns
On resumption, this expression evaluates to the result object of type R, as a const reference.

◆ operator=() [1/2]

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

Move assignment operator.

NOTE: Despite being marked noexcept, this function uses std::lock_guard which may throw. The implementation assumes this can never happen, hence noexcept. Report it if it does, as that would be a bug.

Remarks
Using the moved-from async after this function is undefined behavior.
Parameters
otherThe async object to move the data from

◆ operator=() [2/2]

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

Copy assignment is disabled.

Friends And Related Function Documentation

◆ detail::async::async_base< R >

template<typename R >
friend class detail::async::async_base< R >
friend

Internal use only base class. It serves to prevent await_suspend and await_resume from being used directly.

Warning
For internal use only, do not use.
See also
operator co_await()
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