uvco::Coroutine< T > Class Template Reference

#include <promise.h>

Public Member Functions
template<typename... Args>
	Coroutine (Args &&...)
	Coroutine ()=default
	Coroutine (const Coroutine &other)=delete
Coroutine &	operator= (const Coroutine &other)=delete
	Coroutine (Coroutine &&other)=delete
Coroutine &	operator= (Coroutine &&other)=delete
	~Coroutine ()=default
Promise< T >	get_return_object ()
void	return_value (T value)
std::suspend_never	initial_suspend () noexcept
std::suspend_always	final_suspend () noexcept
void	unhandled_exception ()

Protected Attributes
PromiseCore< T >	core_

Private Types
using	PromiseCore_ = PromiseCore<T>
	PromiseCore_ handles the inner mechanics of resumption and suspension.
using	SharedCore_ = PromiseCore_ *

Detailed Description

template<typename T>
class uvco::Coroutine< T >

A coroutine object used internally by C++20 coroutines ("promise object"). This is the coroutine's "promise_type", i.e. one instance will be allocated for every coroutine invocation, and be part of the coroutine frame. The coroutine frame will be stack-allocated if we're lucky.

Member Typedef Documentation

PromiseCore_

template<typename T>

using uvco::Coroutine< T >::PromiseCore_ = PromiseCore<T>

private

PromiseCore_ handles the inner mechanics of resumption and suspension.

SharedCore_

template<typename T>

using uvco::Coroutine< T >::SharedCore_ = PromiseCore_ *

private

Constructor & Destructor Documentation

Coroutine() [1/4]

template<typename T>

template<typename... Args>

uvco::Coroutine< T >::Coroutine ( Args && ... )

inlineexplicit

This construct forbids coroutines taking rvalue/xvalue arguments, which often enough come from function return values. If a Promise returned by such a coroutine is stored and awaited later, a use-after-free or use-after-return results.

Instead, pass arguments by lvalue reference (which forbids xvalues), or by value (which allows xvalues, and is safe).

The typical violating example is as follows:

Promise<int> coroutine(std::string&& string);
Promise<int> owningCoroutine(std::string string);
Promise<int> lvalueCoroutine(std::string& string);
 
Promise<int> promise = coroutine(fmt::format("Hello World"));
// Error: string is long gone.
co_await promise;
 
// OK
Promise<int> ok = owningCoroutine(fmt::format("Hello World"));
co_await ok;
 
// Compiler Error
Promise<int> bad = lvalueCoroutine(fmt::format("Hello World"));

                                                              {
    // Assert statically that no arg is an rvalue/xvalue reference
    static_assert(
        (!std::is_rvalue_reference_v<Args &&> && ...),
        "Coroutine constructor arguments must not be rvalue references");
  }

Coroutine() [2/4]

template<typename T>

uvco::Coroutine< T >::Coroutine ( )

default

Coroutine object lives and is pinned within the coroutine frame; copy/move is disallowed.

Coroutine() [3/4]

template<typename T>

uvco::Coroutine< T >::Coroutine ( const Coroutine< T > & other )

delete

Coroutine() [4/4]

template<typename T>

uvco::Coroutine< T >::Coroutine ( Coroutine< T > && other )

delete

~Coroutine()

template<typename T>

uvco::Coroutine< T >::~Coroutine ( )

default

Member Function Documentation

final_suspend()

template<typename T>

std::suspend_always uvco::Coroutine< T >::final_suspend ( )

inlinenoexcept

Part of the coroutine protocol: called upon co_return or unhandled exception.

{ return {}; }

get_return_object()

template<typename T>

Promise< T > uvco::Coroutine< T >::get_return_object ( )

inline

Part of the coroutine protocol: Called on first suspension point (co_await) or co_return.

{ return Promise<T>{core_}; }

initial_suspend()

template<typename T>

std::suspend_never uvco::Coroutine< T >::initial_suspend ( )

inlinenoexcept

Part of the coroutine protocol: called after construction of Promise object, i.e. before starting the coroutine.

In uvco, the coroutine always runs at least up to its first suspension point, at which point it may be suspended (if the awaited object is not ready).

                                              {
    core_.setRunning(std::coroutine_handle<Coroutine<T>>::from_promise(*this));
    return {};
  }

operator=() [1/2]

template<typename T>

Coroutine & uvco::Coroutine< T >::operator= ( const Coroutine< T > & other )

delete

operator=() [2/2]

template<typename T>

Coroutine & uvco::Coroutine< T >::operator= ( Coroutine< T > && other )

delete

return_value()

template<typename T>

void uvco::Coroutine< T >::return_value ( T value )

inline

Part of the coroutine protocol: Called by co_return. Schedules the awaiting coroutine for resumption.

                             {
    // Probably cancelled.
    if (core_.slot.has_value() && core_.slot->index() == 1) {
      return;
    }
    BOOST_ASSERT(!core_.slot);
    core_.slot = std::move(value);
    core_.resume();
  }

unhandled_exception()

template<typename T>

void uvco::Coroutine< T >::unhandled_exception ( )

inline

                             {
    core_.except(std::current_exception());
    core_.resume();
  }

Member Data Documentation

core_

template<typename T>

PromiseCore<T> uvco::Coroutine< T >::core_

protected

---

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

• uvco/promise/promise.h
• uvco/promise/promise.cc