# 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_NONE None - invalid Action.
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_REPEAT Indicate that Action is to REPEAT call to current method of Coroutine.
const v_int32 TYPE_WAIT_REPEAT Indicate that Action is to WAIT for some time and then REPEAT call to current method of Coroutine.
const v_int32 TYPE_IO_WAIT Indicate that Action is waiting for IO and should be assigned to corresponding worker.
const v_int32 TYPE_IO_REPEAT Indicate that Action is to repeat previously successful I/O operation.
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.
const v_int32 TYPE_WAIT_LIST Indicate that coroutine should be put on a wait-list provided.
const v_int32 TYPE_WAIT_LIST_WITH_TIMEOUT Indicate that coroutine should be put on a wait-list provided with a timeout.
const v_int32 CODE_IO_WAIT_READ Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.
const v_int32 CODE_IO_WAIT_WRITE Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.
const v_int32 CODE_IO_WAIT_RESCHEDULE Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.
const v_int32 CODE_IO_REPEAT_READ Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.
const v_int32 CODE_IO_REPEAT_WRITE Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.
const v_int32 CODE_IO_REPEAT_RESCHEDULE Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.

# Methods

Return Type Name Summary
[none] Action Multiple implementations:
  1. Default constructor.
  2. Constructor. Create start-coroutine Action.
  3. Constructor. Create yield_to Action.
  4. Constructor. Create Error Action.
  5. Deleted copy-constructor.
  6. Move-constructor.
Action clone Clone action.
Action createActionByType Create action of specific type
Action createIOWaitAction Create TYPE_IO_WAIT Action
Action createIORepeatAction Create TYPE_IO_REPEAT Action
Action createWaitRepeatAction Create TYPE_WAIT_REPEAT Action.
Action createWaitListAction Create TYPE_WAIT_LIST Action.
Action createWaitListActionWithTimeout Create TYPE_WAIT_LIST_WITH_TIMEOUT Action.
[none] ~Action Non-virtual destructor.
bool isError Check if action is an error reporting action.
bool isNone Check if action is of TYPE_NONE.
v_int32 getType Get Action type.
v_int64 getTimePointMicroseconds Get microseconds tick when timer should call coroutine again.
oatpp::v_io_handle getIOHandle Get I/O handle which is passed with this action to I/O worker.
IOEventType getIOEventType This method returns meaningful value only if Action is TYPE_IO_WAIT or TYPE_IO_REPEAT.
v_int32 getIOEventCode Convenience method to get I/O Event code.

# Action::TYPE_NONE

None - invalid Action.

static constexpr const v_int32 TYPE_NONE = 0

# 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_REPEAT

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

static constexpr const v_int32 TYPE_REPEAT = 3

# Action::TYPE_WAIT_REPEAT

Indicate that Action is to WAIT for some time and then REPEAT call to current method of Coroutine.

static constexpr const v_int32 TYPE_WAIT_REPEAT = 4

# Action::TYPE_IO_WAIT

Indicate that Action is waiting for IO and should be assigned to corresponding worker.

static constexpr const v_int32 TYPE_IO_WAIT = 5

# Action::TYPE_IO_REPEAT

Indicate that Action is to repeat previously successful I/O operation.

static constexpr const v_int32 TYPE_IO_REPEAT = 6

# 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 = 7

# Action::TYPE_ERROR

Indicate that Error occurred.

static constexpr const v_int32 TYPE_ERROR = 8

# Action::TYPE_WAIT_LIST

Indicate that coroutine should be put on a wait-list provided.

static constexpr const v_int32 TYPE_WAIT_LIST = 9

# Action::TYPE_WAIT_LIST_WITH_TIMEOUT

Indicate that coroutine should be put on a wait-list provided with a timeout.

static constexpr const v_int32 TYPE_WAIT_LIST_WITH_TIMEOUT = 10

# Action::CODE_IO_WAIT_READ

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.

static constexpr const v_int32 CODE_IO_WAIT_READ = TYPE_IO_WAIT | IOEventType::IO_EVENT_READ

# Action::CODE_IO_WAIT_WRITE

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.

static constexpr const v_int32 CODE_IO_WAIT_WRITE = TYPE_IO_WAIT | IOEventType::IO_EVENT_WRITE

# Action::CODE_IO_WAIT_RESCHEDULE

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_WAIT only.

static constexpr const v_int32 CODE_IO_WAIT_RESCHEDULE = TYPE_IO_WAIT | IOEventType::IO_EVENT_READ | IOEventType::IO_EVENT_WRITE

# Action::CODE_IO_REPEAT_READ

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.

static constexpr const v_int32 CODE_IO_REPEAT_READ = TYPE_IO_REPEAT | IOEventType::IO_EVENT_READ

# Action::CODE_IO_REPEAT_WRITE

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.

static constexpr const v_int32 CODE_IO_REPEAT_WRITE = TYPE_IO_REPEAT | IOEventType::IO_EVENT_WRITE

# Action::CODE_IO_REPEAT_RESCHEDULE

Convenience I/O Action Code. This code is applicable for Action of type TYPE_IO_REPEAT only.

static constexpr const v_int32 CODE_IO_REPEAT_RESCHEDULE = TYPE_IO_REPEAT | IOEventType::IO_EVENT_READ | IOEventType::IO_EVENT_WRITE

# Action::Action

  1. Default constructor.
    Action()
    
  2. Constructor. Create start-coroutine Action.
    Action(AbstractCoroutine* coroutine)
    
  3. Constructor. Create yield_to Action.
    • @param functionPtr - pointer to function.
    Action(const FunctionPtr& functionPtr)
    
  4. Constructor. Create Error Action.
    Action(Error* error)
    
  5. Deleted copy-constructor.
    Action(const Action&) = delete
    
  6. Move-constructor.
    • @param other
    Action(Action&& other)
    

# Action::clone

Clone action.

  • @param action - action to clone.
  • @return - cloned action.

static Action clone(const Action& action)

# Action::createActionByType

Create action of specific type

  • @param type
  • @return

static Action createActionByType(v_int32 type)

# Action::createIOWaitAction

Create TYPE_IO_WAIT Action

  • @param ioHandle - oatpp::v_io_handle.
  • @return - Action.

static Action createIOWaitAction(v_io_handle ioHandle, IOEventType ioEventType)

# Action::createIORepeatAction

Create TYPE_IO_REPEAT Action

  • @param ioHandle - oatpp::v_io_handle.
  • @return - Action.

static Action createIORepeatAction(v_io_handle ioHandle, IOEventType ioEventType)

# Action::createWaitRepeatAction

Create TYPE_WAIT_REPEAT Action.

  • @param timePointMicroseconds - time since epoch.
  • @return - Action.

static Action createWaitRepeatAction(v_int64 timePointMicroseconds)

# Action::createWaitListAction

Create TYPE_WAIT_LIST Action.

  • @param waitList - wait-list to put coroutine on.
  • @return - Action.

static Action createWaitListAction(CoroutineWaitList* waitList)

# Action::createWaitListActionWithTimeout

Create TYPE_WAIT_LIST_WITH_TIMEOUT Action.

  • @param waitList - wait-list to put coroutine on.
  • @param timeout - latest time point at which the coroutine should be continued.
  • @return - Action.

static Action createWaitListActionWithTimeout(CoroutineWaitList* waitList, const std::chrono::steady_clock::time_point& timeout)

# 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() const

# Action::isNone

Check if action is of TYPE_NONE.

  • @return

bool isNone() const

# Action::getType

Get Action type.

  • @return - action type.

v_int32 getType() const

# Action::getTimePointMicroseconds

Get microseconds tick when timer should call coroutine again. This method returns meaningful value only if Action is TYPE_WAIT_REPEAT.

  • @return - microseconds tick.

v_int64 getTimePointMicroseconds() const

# Action::getIOHandle

Get I/O handle which is passed with this action to I/O worker. This method returns meaningful value only if Action is TYPE_IO_WAIT or TYPE_IO_REPEAT.

  • @return - oatpp::v_io_handle.

oatpp::v_io_handle getIOHandle() const

# Action::getIOEventType

This method returns meaningful value only if Action is TYPE_IO_WAIT or TYPE_IO_REPEAT.

  • @return - should return one of

IOEventType getIOEventType() const

# Action::getIOEventCode

Convenience method to get I/O Event code.

  • @return - getType() | getIOEventType().

v_int32 getIOEventCode() const

# Action::IOEventType

Event type qualifier for Actions of type Action::TYPE_IO_WAIT, Action::TYPE_IO_REPEAT.

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

# Action::IOEventType::IO_EVENT_READ

IO event type READ.

IO_EVENT_READ = 256

# Action::IOEventType::IO_EVENT_WRITE

IO event type WRITE.

IO_EVENT_WRITE = 512

# 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)
    

# CoroutineHandle

This class manages coroutines processing state and a chain of coroutine calls.

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

# 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.
[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.
AbstractCoroutine* getParent Get parent coroutine
Action repeat Convenience method to generate Action of type == Action::TYPE_REPEAT.
Action waitRepeat Convenience method to generate Action of type == Action::TYPE_WAIT_REPEAT.
CoroutineStarter waitFor Wait asynchronously for the specified time.
Action ioWait Convenience method to generate Action of type == Action::TYPE_IO_WAIT.
Action ioRepeat Convenience method to generate Action of type == Action::TYPE_IO_WAIT.
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::~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(const FunctionPtr& ptr) = 0

# AbstractCoroutine::handleError

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

  • @param error - oatpp::async::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(Error* error)

# AbstractCoroutine::getParent

Get parent coroutine

  • @return - pointer to a parent coroutine

AbstractCoroutine* getParent() const

# AbstractCoroutine::repeat

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

  • @return - repeat Action.

static Action repeat()

# AbstractCoroutine::waitRepeat

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

  • @return - TYPE_WAIT_REPEAT Action.

static Action waitRepeat(const std::chrono::duration<v_int64, std::micro>& timeout)

# AbstractCoroutine::waitFor

Wait asynchronously for the specified time.

  • @return - repeat Action.

CoroutineStarter waitFor(const std::chrono::duration<v_int64, std::micro>& timeout)

# AbstractCoroutine::ioWait

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

  • @return - TYPE_WAIT_FOR_IO Action.

static Action ioWait(v_io_handle ioHandle, Action::IOEventType ioEventType)

# AbstractCoroutine::ioRepeat

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

  • @return - TYPE_IO_REPEAT Action.

static Action ioRepeat(v_io_handle ioHandle, Action::IOEventType ioEventType)

# AbstractCoroutine::error

  1. Convenience method to generate error reporting Action.
    • @param error - oatpp:async::Error.
    • @return - error reporting Action.
    static Action error(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 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(const 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(const Function& function) 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 { 
  template<typename ...Args>
  class AbstractCoroutineWithResult : public AbstractCoroutine {}
}}

# AbstractCoroutineWithResult::StarterForResult

Class representing Coroutine call for result;

namespace oatpp { namespace async { 
  template<typename ...Args>
  class AbstractCoroutineWithResult : public AbstractCoroutine {
    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.
  • @tparam Args - callback params.
  • @param callback - callback to obtain result.
  • @return - oatpp::async::Action.

template<typename C>
Action callbackTo(Action (C::*callback)(Args...))

# 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<Args...> {}
}}

# 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 _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.

Action call(const AbstractCoroutine::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(const Function& function) 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(const Args&... args)