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...
	~task ()
	Destructor. 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...
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...
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...
bool	done () const noexcept
	Function to check if the task has finished its execution entirely. More...
void	if_this_causes_an_invalid_read_your_promise_was_destroyed_before_your_awaitable____check_your_promise_lifetime ()
	Title :) More...
task &	operator= (const task &)=delete
	Copy assignment is disabled. More...
task &	operator= (task &&other) noexcept
	Move assignment, grabs another task's coroutine handle. 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...
bool	valid () const noexcept
	Check whether this awaitable refers to a valid promise. More...

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

Protected Member Functions
	task (handle_t handle_)
	Construct from a coroutine handle. Internal use only. More...
uint8_t	abandon ()
	Abandons the promise. More...
void	cleanup ()
	Clean up our handle, cancelling any running task. 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_state *	state_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

R	Return 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

other

Task 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

other

Task 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

duration

Maximum 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

Timed

Whether the wait function times out or not

Parameters

do_wait

Function 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

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