uvco::Promise< T > Class Template Reference

#include <promise.h>

Collaboration diagram for uvco::Promise< T >:

Classes
struct	PromiseAwaiter_

Public Types
using	promise_type = Coroutine<T>

Public Member Functions
	Promise (Promise< T > &&other) noexcept
Promise &	operator= (const Promise< T > &other)=delete
	A promise can be copied at low cost.
Promise &	operator= (Promise< T > &&other) noexcept
	Promise (const Promise< T > &other)=delete
	~Promise ()
PromiseAwaiter_	operator co_await () const
bool	ready () const
	Returns if promise has been fulfilled.
T	unwrap ()

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

Protected Member Functions
	Promise (PromiseCore_ &core)
PromiseCore_ *	core ()

Protected Attributes
PromiseCore_ *	core_

Friends
template<typename U>
class	Coroutine
template<typename... Ts>
class	SelectSet

Detailed Description

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

A Promise is the core type of uvco, and returned from coroutines. A coroutine is a function containing either of co_await, co_yield, or co_return. The Promise type defines Coroutine to be the promise type used within a coroutine. The Promise object itself acts as awaitable for awaiting coroutines.

A Promise doesn't need to be constructed directly (and it can't); it is always returned from a coroutine function. Declare a function with a return type of Promise<T> and use co_return to return a value - that's it! Inside the coroutine, you can use co_await etc.

When a Promise is awaited using co_await, the awaiting coroutine is suspended until the promise is resolved. Once the promise is resolved, the suspended coroutine is scheduled to be resumed by Loop at a later time.

The internal state is held in a PromiseCore_ shared by all copies of the same Promise. However, only one coroutine can await a (shared) promise at a time.

See README.md for some examples of how to use coroutines and promises.

NOTE: due to inlining (visibility of the promise code) and other factors, Promise<int> (for example) can be 20% faster than Promise<void>, and also cause fewer allocations. This happens especially when the compiler can elide the coroutine frame allocation for Promise<T>, which it can't do with Promise<void> (which is implemented in a .cc file).

Member Typedef Documentation

promise_type

template<typename T>

using uvco::Promise< T >::promise_type = Coroutine<T>

Part of the coroutine protocol: specifies which class will define the coroutine behavior. In this case, the Coroutine class implements the promise protocol (don't get confused!). This split is useful so that coroutines can use Promise objects as function arguments without implicit construction of their promise objects, which can easily cuase bugs.

Note that the awaiter type is separate (PromiseAwaiter_).

PromiseCore_

template<typename T>

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

protected

PromiseCore_ handles the inner mechanics of resumption and suspension.

Constructor & Destructor Documentation

Promise() [1/3]

template<typename T>

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

inlinenoexcept

                                       : core_{other.core_} {
    other.core_ = nullptr;
  }

Promise() [2/3]

template<typename T>

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

delete

~Promise()

template<typename T>

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

inline

             {
    if (core_ != nullptr) {
      core_->destroyCoroutine();
    }
  }

Promise() [3/3]

template<typename T>

uvco::Promise< T >::Promise ( PromiseCore_ & core )

inlineexplicitprotected

: core_{&core} {}

Member Function Documentation

core()

template<typename T>

PromiseCore_ * uvco::Promise< T >::core ( )

inlineprotected

{ return core_; }

operator co_await()

template<typename T>

PromiseAwaiter_ uvco::Promise< T >::operator co_await ( ) const

inline

Part of the coroutine protocol: called by co_await p where p is a Promise<T>. The returned object is awaited on.

{ return PromiseAwaiter_{*core_}; }

operator=() [1/2]

template<typename T>

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

delete

A promise can be copied at low cost.

operator=() [2/2]

template<typename T>

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

inlinenoexcept

                                                  {
    if (this == &other) {
      return *this;
    }
    if (core_ != nullptr) {
      core_->destroyCoroutine();
    }
    core_ = other.core_;
    other.core_ = nullptr;
    return *this;
  }

ready()

template<typename T>

bool uvco::Promise< T >::ready ( ) const

inlinenodiscard

Returns if promise has been fulfilled.

{ return core_->ready(); }

unwrap()

template<typename T>

T uvco::Promise< T >::unwrap ( )

inline

             {
    if (ready()) {
      auto &slot = core_->slot.value();
      switch (slot.index()) {
      case 0: {
        T value = std::move(std::get<0>(slot));
        core_->slot.reset();
        return value;
      }
      case 1: {
        std::rethrow_exception(std::get<1>(slot));
      }
      default:
        throw UvcoException("PromiseAwaiter_::await_resume: invalid slot");
      }
    }
    throw UvcoException("unwrap called on unfulfilled promise");
  }

Friends And Related Symbol Documentation

Coroutine

template<typename T>

template<typename U>

friend class Coroutine

friend

SelectSet

template<typename T>

template<typename... Ts>

friend class SelectSet

friend

Member Data Documentation

core_

template<typename T>

PromiseCore_* uvco::Promise< T >::core_

protected

---

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

• uvco/promise/promise.h