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

A coroutine task. It starts immediately on construction and can be co_await-ed, making it perfect for parallel coroutines returning a value. More...

#include <coro/task.h>

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

Public Member Functions

 task ()=default
 Default constructor, creates a task not bound to a coroutine. More...
 
 task (const task &)=delete
 Copy constructor is disabled. More...
 
 task (task &&other) noexcept
 Move constructor, grabs another task's coroutine handle. More...
 
taskoperator= (const task &)=delete
 Copy assignment is disabled. More...
 
taskoperator= (task &&other) noexcept
 Move assignment, grabs another task's coroutine handle. More...
 
 ~task ()
 Destructor. More...
 
bool done () const noexcept
 Function to check if the task has finished its execution entirely. More...
 
taskcancel () &noexcept
 Cancel the task, it will stop the next time it uses co_await. On co_await-ing this task, throws dpp::task_cancelled_exception. More...
 
task && cancel () &&noexcept
 Cancel the task, it will stop the next time it uses co_await. On co_await-ing this task, throws dpp::task_cancelled_exception. 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 result_type = R
 The type of the result produced by this task. More...
 

Protected Member Functions

 task (handle_t handle_)
 Construct from a coroutine handle. Internal use only. More...
 
void cleanup ()
 Clean up our handle, cancelling any running task. 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
 Non-owning pointer to the promise, which must be kept alive for the entire lifetime of the awaitable. More...
 

Friends

struct detail::task::promise_t< R >
 

Detailed Description

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

A coroutine task. It starts immediately on construction and can be co_await-ed, making it perfect for parallel coroutines returning a value.

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 our Discord Server.
Template Parameters
RReturn type of the task. Cannot be a reference but can be void.

Member Typedef Documentation

◆ result_type

using dpp::awaitable< R >::result_type = R
protectedinherited

The type of the result produced by this task.

◆ shared_state

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

Constructor & Destructor Documentation

◆ task() [1/4]

template<typename R >
dpp::task< R >::task ( handle_t  handle_)
inlineexplicitprotected

Construct from a coroutine handle. Internal use only.

◆ task() [2/4]

template<typename R >
dpp::task< R >::task ( )
default

Default constructor, creates a task not bound to a coroutine.

◆ task() [3/4]

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

Copy constructor is disabled.

◆ task() [4/4]

template<typename R >
dpp::task< R >::task ( task< R > &&  other)
inlinenoexcept

Move constructor, grabs another task's coroutine handle.

Parameters
otherTask to move the handle from

◆ ~task()

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

Destructor.

Destroys the handle. If the task is still running, it will be cancelled.

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

◆ cancel() [1/2]

template<typename R >
task && dpp::task< R >::cancel ( ) &&
inlinenoexcept

Cancel the task, it will stop the next time it uses co_await. On co_await-ing this task, throws dpp::task_cancelled_exception.

Returns
*this

◆ cancel() [2/2]

template<typename R >
task & dpp::task< R >::cancel ( ) &
inlinenoexcept

Cancel the task, it will stop the next time it uses co_await. On co_await-ing this task, throws dpp::task_cancelled_exception.

Returns
*this

◆ cleanup()

template<typename R >
void dpp::task< R >::cleanup ( )
inlineprotected

Clean up our handle, cancelling any running task.

◆ done()

template<typename R >
bool dpp::task< R >::done ( ) const
inlinenoexcept

Function to check if the task has finished its execution entirely.

Returns
bool Whether the task is finished.

◆ 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 >
task & dpp::task< R >::operator= ( const task< R > &  )
delete

Copy assignment is disabled.

◆ operator=() [2/2]

template<typename R >
task & dpp::task< R >::operator= ( task< R > &&  other)
inlinenoexcept

Move assignment, grabs another task's coroutine handle.

Parameters
otherTask to move the handle from

◆ 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

Friends And Related Function Documentation

◆ detail::task::promise_t< R >

template<typename R >
friend struct detail::task::promise_t< R >
friend

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