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 ()
	Unfulfilled, empty promise.
	Promise (T &&result)
	Fulfilled promise; resolves immediately.
	Promise (Promise< T > &&other) noexcept
Promise &	operator= (const Promise< T > &other)
	A promise can be copied at low cost.
Promise &	operator= (Promise< T > &&other) noexcept
	Promise (const Promise< T > &other)
	~Promise ()
PromiseHandle< T >	handle ()
	Return a handle that can be used to cancel the coroutine.
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.
using	SharedCore_ = PromiseCore_ *

Protected Member Functions
	Promise (SharedCore_ core)
SharedCore_ &	core ()

Protected Attributes
SharedCore_	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; 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.

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.

SharedCore_

template<typename T >

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

protected

Constructor & Destructor Documentation

Promise() [1/5]

template<typename T >

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

inline

Unfulfilled, empty promise.

: core_{makeRefCounted<PromiseCore_>()} {}

Promise() [2/5]

template<typename T >

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

inlineexplicit

Fulfilled promise; resolves immediately.

      : core_{makeRefCounted<PromiseCore_>(std::move(result))} {}

Promise() [3/5]

template<typename T >

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

inlinenoexcept

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

Promise() [4/5]

template<typename T >

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

inline

: core_{other.core_->addRef()} {}

~Promise()

template<typename T >

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

inline

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

Promise() [5/5]

template<typename T >

uvco::Promise< T >::Promise ( SharedCore_  core )

inlineexplicitprotected

: core_{core->addRef()} {}

Member Function Documentation

core()

template<typename T >

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

inlineprotected

{ return core_; }

handle()

template<typename T >

PromiseHandle< T > uvco::Promise< T >::handle ( )

inline

Return a handle that can be used to cancel the coroutine.

{ return PromiseHandle<T>{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 )

inline

A promise can be copied at low cost.

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

operator=() [2/2]

template<typename T >

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

inlinenoexcept

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

ready()

template<typename T >

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

inline

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 std::move(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 >

SharedCore_ uvco::Promise< T >::core_

protected

---

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

• uvco/promise/promise.h