# 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:
|
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
- Default constructor.
Action()
- Constructor. Create start-coroutine Action.
- @param coroutine - pointer to AbstractCoroutine.
Action(AbstractCoroutine* coroutine)
- Constructor. Create yield_to Action.
- @param functionPtr - pointer to function.
Action(const FunctionPtr& functionPtr)
- Constructor. Create Error Action.
- @param error - pointer to oatpp::async::Error.
Action(Error* error)
- Deleted copy-constructor.
Action(const Action&) = delete
- 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:
|
[none] | ~CoroutineStarter | Non-virtual destructor. |
Action | next | Multiple implementations:
|
# CoroutineStarter::CoroutineStarter
- Constructor.
- @param coroutine - coroutine.
CoroutineStarter(AbstractCoroutine* coroutine)
- Deleted copy-constructor.
CoroutineStarter(const CoroutineStarter&) = delete
- Move constructor.
- @param other - other starter.
CoroutineStarter(CoroutineStarter&& other)
# CoroutineStarter::~CoroutineStarter
Non-virtual destructor.
~CoroutineStarter()
# CoroutineStarter::next
- Set final starter action.
Action next(Action&& action)
- 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:
|
# 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
- Convenience method to generate error reporting Action.
- @param error - oatpp:async::Error.
- @return - error reporting Action.
static Action error(Error* error)
- 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:
|
[none] | ~StarterForResult | Non-virtual destructor. |
Action | callbackTo | Set callback for result and return coroutine starting Action. |
# AbstractCoroutineWithResult::StarterForResult::StarterForResult
- Constructor.
- @param coroutine - coroutine.
StarterForResult(AbstractCoroutineWithResult* coroutine) : m_coroutine(coroutine)
- Deleted copy-constructor.
StarterForResult(const StarterForResult&) = delete
- 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.
- @tparam ConstructorArgs - coroutine consrtructor arguments.
- @param args - actual constructor arguments.
- @return - AbstractCoroutineWithResult::StarterForResult.
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)