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 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
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.
[none] Action Multiple implementations:
  1. Constructor. Create start-coroutine Action.
  2. Constructor. Create yield_to Action.
  3. Deleted copy-constructor.
  4. Move-constructor.
[none] ~Action Non-virtual destructor.
bool isError Check if action is an error reporting action.
v_int32 getType Get Action type.
v_int64 getTimePointMicroseconds Get microseconds tick when timer should call coroutine again.
oatpp::data::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::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::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

static Action createIOWaitAction(data::v_io_handle ioHandle, IOEventType ioEventType)

Action::createIORepeatAction

Create TYPE_IO_REPEAT Action

static Action createIORepeatAction(data::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::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. Deleted copy-constructor.
    Action(const Action&) = delete
    
  4. Move-constructor.
    • @param other
    Action(Action&& other)
    

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::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.

oatpp::data::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)
    

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 repeat Convenience method to generate Action of type == Action::TYPE_REPEAT.
Action waitRepeat Convenience method to generate Action of type == Action::TYPE_WAIT_REPEAT.
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 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::repeat

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

  • @return - repeat Action.

Action repeat() const

Coroutine::waitRepeat

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

  • @return - TYPE_WAIT_REPEAT Action.

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

Coroutine::ioWait

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

  • @return - TYPE_WAIT_FOR_IO Action.

Action ioWait(data::v_io_handle ioHandle, Action::IOEventType ioEventType) const

Coroutine::ioRepeat

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

  • @return - TYPE_IO_REPEAT Action.

Action ioRepeat(data::v_io_handle ioHandle, Action::IOEventType ioEventType) 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 waitRepeat Convenience method to generate Action of type == Action::TYPE_WAIT_REPEAT.
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 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::waitRepeat

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

  • @return - TYPE_WAIT_REPEAT Action.

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

CoroutineWithResult::ioWait

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

  • @return - TYPE_WAIT_FOR_IO Action.

Action ioWait(data::v_io_handle ioHandle, Action::IOEventType ioEventType) const

CoroutineWithResult::ioRepeat

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

  • @return - TYPE_IO_REPEAT Action.

Action ioRepeat(data::v_io_handle ioHandle, Action::IOEventType ioEventType) 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)