QCoro::Task< T > Class Template Reference

An asynchronously executed task. More...

#include <qcorotask.h>

Public Types
using	promise_type = detail::TaskPromise< T >
	Promise type of the coroutine. This is required by the C++ standard.
using	value_type = T
	The type of the coroutine return value.

Public Member Functions
	Task () noexcept=default
	Constructs a new empty task.
	Task (const Task &)=delete
	Task cannot be copy-constructed.
	Task (std::coroutine_handle< promise_type > coroutine)
	Constructs a task bound to a coroutine.
	Task (Task &&other) noexcept
	The task can be move-constructed.
	~Task ()
	Destructor.
bool	isReady () const
	Returns whether the task has finished.
auto	operator co_await () const noexcept
	Provides an Awaiter for the coroutine machinery.
Task &	operator= (const Task &)=delete
	Task cannot be copy-assigned.
Task &	operator= (Task &&other) noexcept
	The task can be move-assigned.
template<typename ThenCallback > requires (std::is_invocable_v<ThenCallback> || (!std::is_void_v<T> && std::is_invocable_v<ThenCallback, T>))
auto	then (ThenCallback &&callback)
	A callback to be invoked when the asynchronous task finishes.
template<typename ThenCallback , typename ErrorCallback > requires ((std::is_invocable_v<ThenCallback> || (!std::is_void_v<T> && std::is_invocable_v<ThenCallback, T>)) && std::is_invocable_v<ErrorCallback, const std::exception &>)
auto	then (ThenCallback &&callback, ErrorCallback &&errorCallback)

Detailed Description

template<typename T>
class QCoro::Task< T >

An asynchronously executed task.

When a coroutine is called which has return type Task<T>, the coroutine will construct a new instance of Task<T> which will be returned to the caller when the coroutine is suspended - that is either when it co_awaits another coroutine of finishes executing user code.

In the sense of the interface that the task implements, it is an Awaitable.

Task<T> is constructed by a code generated at the beginning of the coroutine by the compiler (i.e. before the user code). The code first creates a new frame pointer, which internally holds the promise. The promise is of type R::promise_type, where R is the return type of the function (so Task<T>, in our case.

One can think about it as Task being the caller-facing interface and promise being the callee-facing interface.

Definition at line 458 of file qcorotask.h.

Member Typedef Documentation

promise_type

template<typename T >

using QCoro::Task< T >::promise_type = detail::TaskPromise<T>

Promise type of the coroutine. This is required by the C++ standard.

Definition at line 461 of file qcorotask.h.

value_type

template<typename T >

using QCoro::Task< T >::value_type = T

The type of the coroutine return value.

Definition at line 463 of file qcorotask.h.

Constructor & Destructor Documentation

Task() [1/4]

template<typename T >

QCoro::Task< T >::Task ( )

explicitdefaultnoexcept

Constructs a new empty task.

Task() [2/4]

template<typename T >

QCoro::Task< T >::Task ( std::coroutine_handle< promise_type >  coroutine )

inlineexplicit

Constructs a task bound to a coroutine.

Parameters

[in]

coroutine

handle of the coroutine that has constructed the task.

Definition at line 472 of file qcorotask.h.

Task() [3/4]

template<typename T >

QCoro::Task< T >::Task ( const Task< T > &  )

delete

Task cannot be copy-constructed.

Task() [4/4]

template<typename T >

QCoro::Task< T >::Task ( Task< T > &&  other )

inlinenoexcept

The task can be move-constructed.

Definition at line 480 of file qcorotask.h.

~Task()

template<typename T >

QCoro::Task< T >::~Task ( )

inline

Destructor.

Definition at line 501 of file qcorotask.h.

Member Function Documentation

isReady()

template<typename T >

bool QCoro::Task< T >::isReady ( ) const

inline

Returns whether the task has finished.

A task that is ready (represents a finished coroutine) must not attempt to suspend the coroutine again.

Definition at line 516 of file qcorotask.h.

operator co_await()

template<typename T >

auto QCoro::Task< T >::operator co_await ( ) const

inlinenoexcept

Provides an Awaiter for the coroutine machinery.

The coroutine machinery looks for a suitable operator co_await overload for the current Awaitable (this Task). It calls it to obtain an Awaiter object, that is an object that the co_await keyword uses to suspend and resume the coroutine.

Definition at line 527 of file qcorotask.h.

operator=() [1/2]

template<typename T >

Task & QCoro::Task< T >::operator= ( const Task< T > &  )

delete

Task cannot be copy-assigned.

operator=() [2/2]

template<typename T >

Task & QCoro::Task< T >::operator= ( Task< T > &&  other )

inlinenoexcept

The task can be move-assigned.

Definition at line 485 of file qcorotask.h.

then() [1/2]

template<typename T >

template<typename ThenCallback >
requires (std::is_invocable_v<ThenCallback> || (!std::is_void_v<T> && std::is_invocable_v<ThenCallback, T>))

auto QCoro::Task< T >::then ( ThenCallback &&  callback )

inline

A callback to be invoked when the asynchronous task finishes.

In some scenarios it is not possible to co_await a coroutine (for example from a third-party code that cannot be changed to be a coroutine). In that case, chaining a then() callback is a possible solution how to handle a result of a coroutine without co_awaiting it.

Parameters

callback

A function or a function object that can be invoked without arguments (discarding the result of the coroutine) or with a single argument of type T that is type matching the return type of the coroutine or is implicitly constructible from the return type returned by the coroutine.

Returns

Returns Task<R> where R is the return type of the callback, so that the result of the then() action can be co_awaited, if desired. If the callback returns an awaitable (Task<R>) then the result of then is the awaitable.

Definition at line 571 of file qcorotask.h.

then() [2/2]

template<typename T >

template<typename ThenCallback , typename ErrorCallback >
requires ((std::is_invocable_v<ThenCallback> || (!std::is_void_v<T> && std::is_invocable_v<ThenCallback, T>)) && std::is_invocable_v<ErrorCallback, const std::exception &>)

auto QCoro::Task< T >::then ( ThenCallback &&  callback, ErrorCallback &&  errorCallback  )

inline

Definition at line 580 of file qcorotask.h.

---

The documentation for this class was generated from the following file:

• qcorotask.h