Coroutine.hpp

This File On Github
Ask A Question

API: latest
module: oatpp
#include "oatpp/core/async/Coroutine.hpp"

Action

Class Action represents an asynchronous action.

namespace oatpp { namespace async { 
  class Action {}
}}

Fields

Type Name Summary
const v_int32 TYPE_COROUTINE Indicate that Action is to start coroutine.
const v_int32 TYPE_YIELD_TO Indicate that Action is to YIELD control to other method of Coroutine.
const v_int32 TYPE_WAIT_RETRY Indicate that Action is to WAIT and then RETRY call to current method of Coroutine.
const v_int32 TYPE_REPEAT Indicate that Action is to REPEAT call to current method of Coroutine.
const v_int32 TYPE_FINISH Indicate that Action is to FINISH current Coroutine and return control to a caller-Coroutine.
const v_int32 TYPE_ERROR Indicate that Error occurred.

Methods

Return Type Name Summary
[none] Action Multiple implementations:
  1. Constructor. Create start-coroutine Action.
  2. Constructor. Create yield_to Action.
  3. Create Action by type.
  4. Deleted copy-constructor.
[none] ~Action Non-virtual destructor.
bool isError Check if action is an error reporting action.
v_int32 getType Get Action type.

Action::TYPE_COROUTINE

Indicate that Action is to start coroutine.

static constexpr const v_int32 TYPE_COROUTINE = 1

Action::TYPE_YIELD_TO

Indicate that Action is to YIELD control to other method of Coroutine.

static constexpr const v_int32 TYPE_YIELD_TO = 2

Action::TYPE_WAIT_RETRY

Indicate that Action is to WAIT and then RETRY call to current method of Coroutine.

static constexpr const v_int32 TYPE_WAIT_RETRY = 3

Action::TYPE_REPEAT

Indicate that Action is to REPEAT call to current method of Coroutine.

static constexpr const v_int32 TYPE_REPEAT = 4

Action::TYPE_FINISH

Indicate that Action is to FINISH current Coroutine and return control to a caller-Coroutine.

static constexpr const v_int32 TYPE_FINISH = 5

Action::TYPE_ERROR

Indicate that Error occurred.

static constexpr const v_int32 TYPE_ERROR = 6

Action::Action

  1. Constructor. Create start-coroutine Action.
    Action(AbstractCoroutine* coroutine)
    
  2. Constructor. Create yield_to Action.
    • @param functionPtr - pointer to function.
    Action(FunctionPtr functionPtr)
    
  3. Create Action by type.
    • @param type - Action type.
    Action(v_int32 type)
    
  4. Deleted copy-constructor.
    Action(const Action&) = delete
    

Action::~Action

Non-virtual destructor.

~Action()

Action::isError

Check if action is an error reporting action.

  • @return true if action is an error reporting action.

bool isError()

Action::getType

Get Action type.

  • @return - action type.

v_int32 getType()

CoroutineStarter

CoroutineStarter of Coroutine calls.

namespace oatpp { namespace async { 
  class CoroutineStarter {}
}}

Methods

Return Type Name Summary
[none] CoroutineStarter Multiple implementations:
  1. Constructor.
  2. Deleted copy-constructor.
  3. Move constructor.
[none] ~CoroutineStarter Non-virtual destructor.
Action next Multiple implementations:
  1. Set final starter action.
  2. Pipeline coroutine starter.

CoroutineStarter::CoroutineStarter

  1. Constructor.
    • @param coroutine - coroutine.
    CoroutineStarter(AbstractCoroutine* coroutine)
    
  2. Deleted copy-constructor.
    CoroutineStarter(const CoroutineStarter&) = delete
    
  3. Move constructor.
    • @param other - other starter.
    CoroutineStarter(CoroutineStarter&& other)
    

CoroutineStarter::~CoroutineStarter

Non-virtual destructor.

~CoroutineStarter()

CoroutineStarter::next

  1. Set final starter action.
    Action next(Action&& action)
    
  2. Pipeline coroutine starter.
    • @param starter - starter to add.
    • @return - this starter.
    CoroutineStarter& next(CoroutineStarter&& starter)
    

AbstractCoroutine

Abstract Coroutine. Base class for Coroutines. It provides state management, coroutines stack management and error reporting functionality.

namespace oatpp { namespace async { 
  class AbstractCoroutine : public oatpp::base::Countable {}
}}

Typedefs

Type Name Summary
oatpp::async::Action Action Convenience typedef for Action

Methods

Return Type Name Summary
[none] AbstractCoroutine Constructor.
Action iterate Make one Coroutine iteration.
[none] ~AbstractCoroutine Virtual Destructor
Action act Entrypoint of Coroutine.
Action call Call function of Coroutine specified by ptr.
Action handleError Default implementation of handleError(error) function.
bool finished Check if coroutine is finished
AbstractCoroutine* getParent Get parent coroutine
Action error Multiple implementations:
  1. Convenience method to generate error reporting Action.
  2. Convenience method to generate error reporting Action.

AbstractCoroutine::Action

Convenience typedef for Action

typedef oatpp::async::Action Action

AbstractCoroutine::AbstractCoroutine

Constructor.

AbstractCoroutine()

AbstractCoroutine::iterate

Make one Coroutine iteration.

  • @return - control Action.

Action iterate()

AbstractCoroutine::~AbstractCoroutine

Virtual Destructor

virtual ~AbstractCoroutine() = default

AbstractCoroutine::act

Entrypoint of Coroutine.

  • @return - Action

virtual Action act() = 0

AbstractCoroutine::call

Call function of Coroutine specified by ptr.
This method is called from iterate().
Coroutine keeps track of function ptr and calls corresponding function on each iteration. When Coroutine starts, function ptr points to act().

  • @param ptr - pointer of the function to call.
  • @return - Action.

virtual Action call(FunctionPtr ptr) = 0

AbstractCoroutine::handleError

Default implementation of handleError(error) function. User may override this function in order to handle errors.

  • @param error - error.
  • @return - Action. If handleError function returns Error, current coroutine will finish, return control to caller coroutine and handleError is called for caller coroutine.

virtual Action handleError(const std::shared_ptr<const Error>& error)

AbstractCoroutine::finished

Check if coroutine is finished

  • @return - true if finished

bool finished() const

AbstractCoroutine::getParent

Get parent coroutine

  • @return - pointer to a parent coroutine

AbstractCoroutine* getParent() const

AbstractCoroutine::error

  1. Convenience method to generate error reporting Action.
    • @param message - error message.
    • @return - error reporting Action.
    Action error(const std::shared_ptr<const Error>& error)
    
  2. Convenience method to generate error reporting Action.
    • @tparam E - Error class type.
    • @tparam Args - Error constructor arguments.
    • @param args - actual error constructor arguments.
    • @return - error reporting oatpp::async::Action.
    template<class E, typename ... Args>
    Action error(Args... args)
    

Coroutine

Coroutine template.
Example usage:
class MyCoroutine : public oatpp::async::Coroutine<MyCoroutine>

  • @tparam T - child class type

namespace oatpp { namespace async { 
  template<class T>
  class Coroutine : public AbstractCoroutine {}
}}

Methods

Return Type Name Summary
CoroutineStarter start Create coroutine and return it's starter
Action call Call function of Coroutine specified by ptr.
Action yieldTo Convenience method to generate Action of type == Action::TYPE_YIELD_TO.
Action waitRetry Convenience method to generate Action of type == Action::TYPE_WAIT_RETRY.
Action repeat Convenience method to generate Action of type == Action::TYPE_REPEAT.
Action finish Convenience method to generate Action of type == Action::TYPE_FINISH.

Coroutine::start

Create coroutine and return it's starter

  • @tparam ConstructorArgs - coroutine constructor arguments.
  • @param args - actual coroutine constructor arguments.
  • @return - oatpp::async::CoroutineStarter.

template<typename ...ConstructorArgs>
static CoroutineStarter start(ConstructorArgs... args)

Coroutine::call

Call function of Coroutine specified by ptr.
Overridden AbstractCoroutine::call() method.

  • @param ptr - pointer of the function to call.
  • @return - Action.

Action call(FunctionPtr ptr) override

Coroutine::yieldTo

Convenience method to generate Action of type == Action::TYPE_YIELD_TO.

  • @param function - pointer to function.
  • @return - yield Action.

Action yieldTo(Function function) const

Coroutine::waitRetry

Convenience method to generate Action of type == Action::TYPE_WAIT_RETRY.

  • @return - WAIT_RETRY Action.

Action waitRetry() const

Coroutine::repeat

Convenience method to generate Action of type == Action::TYPE_REPEAT.

  • @return - repeat Action.

Action repeat() const

Coroutine::finish

Convenience method to generate Action of type == Action::TYPE_FINISH.

  • @return - finish Action.

Action finish() const

AbstractCoroutineWithResult

Abstract coroutine with result.

namespace oatpp { namespace async { 
  class AbstractCoroutineWithResult : public AbstractCoroutine {}
}}

AbstractCoroutineWithResult::StarterForResult

Class representing Coroutine call for result;

namespace oatpp { namespace async { 
  class AbstractCoroutineWithResult : public AbstractCoroutine {
    template<typename ...Args >
    class StarterForResult {}
  };
}}

Methods

Return Type Name Summary
[none] StarterForResult Multiple implementations:
  1. Constructor.
  2. Deleted copy-constructor.
  3. Move constructor.
[none] ~StarterForResult Non-virtual destructor.
Action callbackTo Set callback for result and return coroutine starting Action.

AbstractCoroutineWithResult::StarterForResult::StarterForResult

  1. Constructor.
    • @param coroutine - coroutine.
    StarterForResult(AbstractCoroutineWithResult* coroutine)
      : m_coroutine(coroutine)
    
  2. Deleted copy-constructor.
    StarterForResult(const StarterForResult&) = delete
    
  3. Move constructor.
    • @param other - other starter.
    StarterForResult(StarterForResult&& other)
      : m_coroutine(other.m_coroutine)
    

AbstractCoroutineWithResult::StarterForResult::~StarterForResult

Non-virtual destructor.

~StarterForResult()

AbstractCoroutineWithResult::StarterForResult::callbackTo

Set callback for result and return coroutine starting Action.

  • @tparam C - caller coroutine type.
  • @param callback - callback to obtain result.
  • @return - oatpp::async::Action.

template<class C>
Action callbackTo(Callback<C> callback)

CoroutineWithResult

Coroutine with result template.
Example usage:
class CoroutineWithResult : public oatpp::async::CoroutineWithResult<CoroutineWithResult, const char*>

  • @tparam T - child class type.
  • @tparam Args - return argumet type.

namespace oatpp { namespace async { 
  template<class T, typename ...Args>
  class CoroutineWithResult : public AbstractCoroutineWithResult {}
}}

Methods

Return Type Name Summary
CoroutineStarterForResult<Args...> startForResult Call coroutine for result.
Action call Call function of Coroutine specified by ptr.
Action yieldTo Convenience method to generate Action of type == Action::TYPE_YIELD_TO.
Action waitRetry Convenience method to generate Action of type == Action::TYPE_WAIT_RETRY.
Action repeat Convenience method to generate Action of type == Action::TYPE_REPEAT.
Action _return Call caller's Callback passing returned value, and generate Action of type == Action::TYPE_FINISH.

CoroutineWithResult::startForResult

Call coroutine for result.

template<typename ...ConstructorArgs>
static CoroutineStarterForResult<Args...> startForResult(ConstructorArgs... args)

CoroutineWithResult::call

Call function of Coroutine specified by ptr.
Overridden AbstractCoroutine::call() method.

  • @param ptr - pointer of the function to call.
  • @return - Action.

virtual Action call(FunctionPtr ptr) override

CoroutineWithResult::yieldTo

Convenience method to generate Action of type == Action::TYPE_YIELD_TO.

  • @param function - pointer to function.
  • @return - yield Action.

Action yieldTo(Function function) const

CoroutineWithResult::waitRetry

Convenience method to generate Action of type == Action::TYPE_WAIT_RETRY.

  • @return - WAIT_RETRY Action.

Action waitRetry() const

CoroutineWithResult::repeat

Convenience method to generate Action of type == Action::TYPE_REPEAT.

  • @return - repeat Action.

Action repeat() const

CoroutineWithResult::_return

Call caller's Callback passing returned value, and generate Action of type == Action::TYPE_FINISH.

  • @param args - argumets to be passed to callback.
  • @return - finish Action.

Action _return(Args... args)