uvco::PromiseCore< T > Class Template Reference

#include <promise_core.h>

Inheritance diagram for uvco::PromiseCore< T >:

Collaboration diagram for uvco::PromiseCore< T >:

Public Member Functions
	PromiseCore ()=default
	PromiseCore (const PromiseCore &)=delete
	PromiseCore (PromiseCore &&)=delete
PromiseCore &	operator= (const PromiseCore &)=delete
PromiseCore &	operator= (PromiseCore &&)=delete
	PromiseCore (T &&value)
virtual void	setHandle (std::coroutine_handle<> handle)
	Set the coroutine to be resumed once a result is ready.
void	resetHandle ()
void	cancel ()
bool	willResume ()
	Checks if a coroutine is waiting on a promise belonging to this core.
bool	ready () const
	Checks if a value is present in the slot.
bool	stale () const
virtual void	resume ()
virtual	~PromiseCore ()
void	except (const std::exception_ptr &exc)
Public Member Functions inherited from uvco::RefCounted< PromiseCore< T > >
	RefCounted (const RefCounted &other)=default
	RefCounted (RefCounted &&other) noexcept
RefCounted &	operator= (const RefCounted &other)=default
RefCounted &	operator= (RefCounted &&other) noexcept
virtual	~RefCounted ()=default
virtual T *	addRef ()
virtual void	delRef ()

Public Attributes
std::optional< std::variant< T, std::exception_ptr > >	slot
	The slot contains the result once obtained.

Protected Attributes
std::optional< std::coroutine_handle<> >	handle_
PromiseState	state_ = PromiseState::init

Additional Inherited Members
Protected Member Functions inherited from uvco::RefCounted< PromiseCore< T > >
	RefCounted ()=default

Detailed Description

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

A PromiseCore is shared among copies of promises waiting for the same coroutine. It contains a state, a result (of type T), and potentially a coroutine_handle of the coroutine waiting on it. Only one coroutine may await a promise, this is enforced here.

A PromiseCore is RefCounted; this reduces the overhead of shared_ptr by as much as 50% in Debug mode and 30% in clang Release mode. However, this is only expected to occur in promise-heavy code without involvement of libuv (such as pure channels).

The canonical way would be just using shared_ptr, which is likely fast enough. But we're experimenting, so let's have fun.

Constructor & Destructor Documentation

PromiseCore() [1/4]

template<typename T >

uvco::PromiseCore< T >::PromiseCore ( )

default

PromiseCore() [2/4]

template<typename T >

uvco::PromiseCore< T >::PromiseCore ( const PromiseCore< T > &  )

delete

PromiseCore() [3/4]

template<typename T >

uvco::PromiseCore< T >::PromiseCore ( PromiseCore< T > &&  )

delete

PromiseCore() [4/4]

template<typename T >

uvco::PromiseCore< T >::PromiseCore ( T &&  value )

inlineexplicit

      : slot{std::move(value)}, state_{PromiseState::finished} {}

~PromiseCore()

template<typename T >

virtual uvco::PromiseCore< T >::~PromiseCore ( )

inlinevirtual

Destroys a promise core. Also destroys a coroutine if there is one suspended and has not been resumed yet. In that case, a warning is emitted ("PromiseCore destroyed without ever being resumed").

                         {
    if (state_ != PromiseState::finished) {
      fmt::print(
          stderr,
          "PromiseCore destroyed without ever being resumed ({}, state = {})\n",
          typeid(T).name(), static_cast<int>(state_));
    }
    // This only happens if the awaiting coroutine has never been resumed, but
    // the last promise provided by it is gone (in turn calling
    // ~PromiseCore()). Important: we may only destroy a suspended coroutine,
    // not a finished one.
    if (handle_) {
      handle_->destroy();
    }
  }

Member Function Documentation

cancel()

template<typename T >

void uvco::PromiseCore< T >::cancel ( )

inline

Cancel a promise. The awaiter, if present, will immediately receive an exception. The coroutine itself will keep running, however. (This may be changed later)

                {
    if (state_ == PromiseState::init || state_ == PromiseState::waitedOn) {
      BOOST_ASSERT(!ready());
      // Fill the slot with an exception, so that the coroutine can be resumed.
      // Double-check `if` for release builds.
      if (!slot) {
        slot = std::make_exception_ptr(
            UvcoException(UV_ECANCELED, "Promise cancelled"));
      }
      resume();
    }
    // else: the underlying coroutine has already returned, so there is no need
    // to cancel it.
  }

except()

template<typename T >

void uvco::PromiseCore< T >::except ( const std::exception_ptr &  exc )

inline

{ slot = exc; }

operator=() [1/2]

template<typename T >

PromiseCore & uvco::PromiseCore< T >::operator= ( const PromiseCore< T > &  )

delete

operator=() [2/2]

template<typename T >

PromiseCore & uvco::PromiseCore< T >::operator= ( PromiseCore< T > &&  )

delete

ready()

template<typename T >

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

inline

Checks if a value is present in the slot.

{ return slot.has_value(); }

resetHandle()

template<typename T >

void uvco::PromiseCore< T >::resetHandle ( )

inline

Reset the handle, so that the coroutine is not resumed anymore. This is required for SelectSet.

                     {
    BOOST_ASSERT((state_ == PromiseState::waitedOn && handle_) ||
                 (state_ == PromiseState::finished && !handle_) ||
                 (state_ == PromiseState::init && !handle_));
    if (state_ == PromiseState::waitedOn) {
      handle_.reset();
      state_ = PromiseState::init;
    }
  }

resume()

template<typename T >

virtual void uvco::PromiseCore< T >::resume ( )

inlinevirtual

Resume a suspended coroutine waiting on the associated coroutine by enqueuing it in the global event loop.

A promise core can only be resumed once.

Reimplemented in uvco::MultiPromiseCore< T >.

                        {
    if (handle_) {
      BOOST_ASSERT(state_ == PromiseState::waitedOn);
      state_ = PromiseState::resuming;
      auto resume = *handle_;
      handle_.reset();
      Loop::enqueue(resume);
    } else {
      // This occurs if no co_await has occured until resume. Either the
      // promise was not co_awaited, or the producing coroutine immediately
      // returned a value. (await_ready() == true)
    }
 
    switch (state_) {
    case PromiseState::init:
      // Coroutine returns but nobody has awaited yet. This is fine.
      state_ = PromiseState::finished;
      break;
    case PromiseState::resuming:
      // Not entirely correct, but the resumed awaiting coroutine is not coming
      // back to us.
      state_ = PromiseState::finished;
      break;
    case PromiseState::waitedOn:
      // state is waitedOn, but no handle is set - that's an error.
      BOOST_ASSERT_MSG(
          false,
          "PromiseCore::resume() called without handle in state waitedOn");
      break;
    case PromiseState::finished:
      // Happens in MultiPromiseCore on co_return if the co_awaiter has lost
      // interest. Harmless if !handle_ (asserted above).
      break;
    }
  }

setHandle()

template<typename T >

virtual void uvco::PromiseCore< T >::setHandle ( std::coroutine_handle<>  handle )

inlinevirtual

Set the coroutine to be resumed once a result is ready.

Reimplemented in uvco::MultiPromiseCore< T >.

                                                       {
    if (state_ != PromiseState::init) {
      throw UvcoException("PromiseCore is already awaited or has finished");
    }
    handle_ = handle;
    state_ = PromiseState::waitedOn;
  }

stale()

template<typename T >

bool uvco::PromiseCore< T >::stale ( ) const

inline

Checks if the coroutine has returned, and the results have been fetched (i.e. after co_return -> co_await).

                                   {
    return state_ == PromiseState::finished && !ready();
  }

willResume()

template<typename T >

bool uvco::PromiseCore< T >::willResume ( )

inline

Checks if a coroutine is waiting on a promise belonging to this core.

{ return handle_.has_value(); }

Member Data Documentation

handle_

template<typename T >

std::optional<std::coroutine_handle<> > uvco::PromiseCore< T >::handle_

protected

slot

template<typename T >

std::optional<std::variant<T, std::exception_ptr> > uvco::PromiseCore< T >::slot

The slot contains the result once obtained.

state_

template<typename T >

PromiseState uvco::PromiseCore< T >::state_ = PromiseState::init

protected

---

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

• uvco/promise/promise_core.h