D++ (DPP)
C++ Discord API Bot Library
dpp::task Class 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...

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...
 
 ~task ()
 Destructor. More...
 
taskoperator= (const task &)=delete
 Copy assignment is disabled. More...
 
taskoperator= (task &&other) noexcept
 Move assignment, grabs another task's coroutine handle. More...
 
bool done () const noexcept
 Function to check if the task has finished its execution entirely. More...
 
dpp::task< R > & 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...
 
bool await_ready () const
 Check whether or not a call to co_await will suspend the caller. More...
 
auto & operator co_await () &noexcept
 Suspend the current coroutine until the task completes. More...
 
const auto & operator co_await () const &noexcept
 Suspend the current coroutine until the task completes. More...
 
auto && operator co_await () &&noexcept
 Suspend the current coroutine until the task completes. More...
 

Friends

class detail::task::task_base< R >
 Internal use only base class containing common logic between task<R> and task<void>. It also serves to prevent await_suspend and await_resume from being used directly. More...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ task() [1/3]

dpp::task::task ( )
default

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

◆ task() [2/3]

dpp::task::task ( const task )
delete

Copy constructor is disabled.

◆ task() [3/3]

dpp::task::task ( task &&  other)
noexcept

Move constructor, grabs another task's coroutine handle.

Parameters
otherTask to move the handle from

◆ ~task()

dpp::task::~task ( )

Destructor.

Destroys the handle.

Warning
The coroutine must be finished before this is called, otherwise it runs the risk of being resumed after it is destroyed, resuming in use-after-free undefined behavior.

Member Function Documentation

◆ await_ready()

bool dpp::task::await_ready ( ) const

Check whether or not a call to co_await will suspend the caller.

This function is called by the standard library as a first step when using co_await. If it returns true then the caller is not suspended.

Exceptions
logic_exceptionif the task is empty.
Returns
bool Whether not to suspend the caller or not

◆ cancel()

dpp::task<R>& dpp::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.

◆ done()

bool dpp::task::done ( ) const
noexcept

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

Returns
bool Whether the task is finished.

◆ operator co_await() [1/3]

auto&& dpp::task::operator co_await ( ) &&
inlinenoexcept

Suspend the current coroutine until the task completes.

Exceptions
Onresumption, any exception thrown by the coroutine is propagated to the caller.
Returns
On resumption, this expression evaluates to the result object of type R, as an rvalue reference.

◆ operator co_await() [2/3]

auto& dpp::task::operator co_await ( ) &
inlinenoexcept

Suspend the current coroutine until the task completes.

Exceptions
Onresumption, any exception thrown by the coroutine is propagated to the caller.
Returns
On resumption, this expression evaluates to the result object of type R, as a reference.

◆ operator co_await() [3/3]

const auto& dpp::task::operator co_await ( ) const &
inlinenoexcept

Suspend the current coroutine until the task completes.

Exceptions
Onresumption, any exception thrown by the coroutine is propagated to the caller.
Returns
On resumption, this expression evaluates to the result object of type R, as a const reference.

◆ operator=() [1/2]

task& dpp::task::operator= ( const task )
delete

Copy assignment is disabled.

◆ operator=() [2/2]

task& dpp::task::operator= ( task &&  other)
noexcept

Move assignment, grabs another task's coroutine handle.

Parameters
otherTask to move the handle from

Friends And Related Function Documentation

◆ detail::task::task_base< R >

friend class detail::task::task_base< R >
friend

Internal use only base class containing common logic between task<R> and task<void>. It also 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