KiCad PCB EDA Suite
Loading...
Searching...
No Matches
COROUTINE< ReturnType, ArgType > Class Template Reference

Implement a coroutine. More...

#include <coroutine.h>

Classes

class  CALL_CONTEXT
 
struct  CONTEXT_T
 
struct  INVOCATION_ARGS
 
struct  STACK_DELETER
 A functor that frees the stack. More...
 

Public Member Functions

 COROUTINE ()
 
template<class T>
 COROUTINE (T *object, ReturnType(T::*ptr)(ArgType))
 Create a coroutine from a member method of an object.
 
 COROUTINE (std::function< ReturnType(ArgType)> aEntry)
 Create a coroutine from a delegate object.
 
 ~COROUTINE ()
 
void KiYield ()
 Stop execution of the coroutine and returns control to the caller.
 
void KiYield (ReturnType &aRetVal)
 KiYield with a value.
 
void RunMainStack (std::function< void()> func)
 Run a functor inside the application main stack context.
 
bool Call (ArgType aArg)
 Start execution of a coroutine, passing args as its arguments.
 
bool Call (const COROUTINE &aCor, ArgType aArg)
 Start execution of a coroutine, passing args as its arguments.
 
bool Resume ()
 Resume execution of a previously yielded coroutine.
 
bool Resume (const COROUTINE &aCor)
 Resume execution of a previously yielded coroutine.
 
const ReturnType & ReturnValue () const
 Return the yielded value (the argument KiYield() was called with).
 
bool Running () const
 

Private Member Functions

INVOCATION_ARGSdoCall (INVOCATION_ARGS *aInvArgs, ArgType aArgs)
 
INVOCATION_ARGSdoResume (INVOCATION_ARGS *args)
 
INVOCATION_ARGSjumpIn (INVOCATION_ARGS *args)
 
void jumpOut ()
 

Static Private Member Functions

static size_t SystemPageSize ()
 The size of the mappable memory page size.
 
static void * MapMemory (size_t aAllocSize)
 Map a page-aligned memory region into our address space.
 
static void GuardMemory (void *aAddress, size_t aGuardSize)
 Change protection of memory page(s) to act as stack guards.
 
static void callerStub (intptr_t aData)
 

Private Attributes

std::unique_ptr< char[], struct STACK_DELETERm_stack
 Coroutine stack.
 
int m_stacksize
 
std::function< ReturnType(ArgType)> m_func
 
bool m_running
 
std::remove_reference< ArgType >::type * m_args
 Pointer to coroutine entry arguments stripped of references to avoid compiler errors.
 
CONTEXT_T m_caller
 Saved caller context.
 
CALL_CONTEXTm_callContext
 Main stack information.
 
CONTEXT_T m_callee
 Saved coroutine context.
 
ReturnType m_retVal
 

Detailed Description

template<typename ReturnType, typename ArgType>
class COROUTINE< ReturnType, ArgType >

Implement a coroutine.

Wikipedia has a good explanation:

"Coroutines are computer program components that generalize subroutines to allow multiple entry points for suspending and resuming execution at certain locations. Coroutines are well-suited for implementing more familiar program components such as cooperative tasks, exceptions, event loop, iterators, infinite lists and pipes."

In other words, a coroutine can be considered a lightweight thread - which can be preempted only when it deliberately yields the control to the caller. This way, we avoid concurrency problems such as locking / race conditions.

Uses libcontext library to do the actual context switching.

This particular version takes a DELEGATE as an entry point, so it can invoke methods within a given object as separate coroutines.

See coroutine_example.cpp for sample code.

Definition at line 83 of file coroutine.h.

Constructor & Destructor Documentation

◆ COROUTINE() [1/3]

template<typename ReturnType, typename ArgType>
COROUTINE< ReturnType, ArgType >::COROUTINE ( )
inline

◆ COROUTINE() [2/3]

template<typename ReturnType, typename ArgType>
template<class T>
COROUTINE< ReturnType, ArgType >::COROUTINE ( T * object,
ReturnType(T::* ptr )(ArgType) )
inline

Create a coroutine from a member method of an object.

Definition at line 191 of file coroutine.h.

◆ COROUTINE() [3/3]

template<typename ReturnType, typename ArgType>
COROUTINE< ReturnType, ArgType >::COROUTINE ( std::function< ReturnType(ArgType)> aEntry)
inline

Create a coroutine from a delegate object.

Definition at line 199 of file coroutine.h.

◆ ~COROUTINE()

template<typename ReturnType, typename ArgType>
COROUTINE< ReturnType, ArgType >::~COROUTINE ( )
inline

Definition at line 217 of file coroutine.h.

Member Function Documentation

◆ Call() [1/2]

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::Call ( ArgType aArg)
inline

Start execution of a coroutine, passing args as its arguments.

Call this method from the application main stack only.

Returns
true if the coroutine has yielded and false if it has finished its execution (returned).

Definition at line 274 of file coroutine.h.

Referenced by TOOL_MANAGER::dispatchInternal().

◆ Call() [2/2]

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::Call ( const COROUTINE< ReturnType, ArgType > & aCor,
ArgType aArg )
inline

Start execution of a coroutine, passing args as its arguments.

Call this method for a nested coroutine invocation.

Returns
true if the coroutine has yielded and false if it has finished its execution (returned).

Definition at line 300 of file coroutine.h.

◆ callerStub()

template<typename ReturnType, typename ArgType>
static void COROUTINE< ReturnType, ArgType >::callerStub ( intptr_t aData)
inlinestaticprivate

Definition at line 501 of file coroutine.h.

◆ doCall()

template<typename ReturnType, typename ArgType>
INVOCATION_ARGS * COROUTINE< ReturnType, ArgType >::doCall ( INVOCATION_ARGS * aInvArgs,
ArgType aArgs )
inlineprivate

Definition at line 375 of file coroutine.h.

Referenced by COROUTINE< int, int >::Call(), and COROUTINE< int, int >::Call().

◆ doResume()

template<typename ReturnType, typename ArgType>
INVOCATION_ARGS * COROUTINE< ReturnType, ArgType >::doResume ( INVOCATION_ARGS * args)
inlineprivate

◆ GuardMemory()

template<typename ReturnType, typename ArgType>
static void COROUTINE< ReturnType, ArgType >::GuardMemory ( void * aAddress,
size_t aGuardSize )
inlinestaticprivate

Change protection of memory page(s) to act as stack guards.

Definition at line 481 of file coroutine.h.

Referenced by COROUTINE< int, int >::doCall().

◆ jumpIn()

template<typename ReturnType, typename ArgType>
INVOCATION_ARGS * COROUTINE< ReturnType, ArgType >::jumpIn ( INVOCATION_ARGS * args)
inlineprivate

Definition at line 520 of file coroutine.h.

Referenced by COROUTINE< int, int >::doCall(), and COROUTINE< int, int >::doResume().

◆ jumpOut()

template<typename ReturnType, typename ArgType>
void COROUTINE< ReturnType, ArgType >::jumpOut ( )
inlineprivate

◆ KiYield() [1/2]

template<typename ReturnType, typename ArgType>
void COROUTINE< ReturnType, ArgType >::KiYield ( )
inline

Stop execution of the coroutine and returns control to the caller.

After a yield, Call() or Resume() methods invoked by the caller will immediately return true, indicating that we are not done yet, just asleep.

Definition at line 237 of file coroutine.h.

Referenced by TOOL_MANAGER::ScheduleWait().

◆ KiYield() [2/2]

template<typename ReturnType, typename ArgType>
void COROUTINE< ReturnType, ArgType >::KiYield ( ReturnType & aRetVal)
inline

KiYield with a value.

Passe a value of given type to the caller. Useful for implementing generator objects.

Definition at line 247 of file coroutine.h.

◆ MapMemory()

template<typename ReturnType, typename ArgType>
static void * COROUTINE< ReturnType, ArgType >::MapMemory ( size_t aAllocSize)
inlinestaticprivate

Map a page-aligned memory region into our address space.

Definition at line 464 of file coroutine.h.

Referenced by COROUTINE< int, int >::doCall().

◆ Resume() [1/2]

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::Resume ( )
inline

Resume execution of a previously yielded coroutine.

Call this method only from the main application stack.

Returns
true if the coroutine has yielded again and false if it has finished its execution (returned).

Definition at line 320 of file coroutine.h.

Referenced by TOOL_MANAGER::dispatchInternal(), and TOOL_MANAGER::ShutdownTool().

◆ Resume() [2/2]

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::Resume ( const COROUTINE< ReturnType, ArgType > & aCor)
inline

Resume execution of a previously yielded coroutine.

Call this method for a nested coroutine invocation.

Returns
true if the coroutine has yielded again and false if it has finished its execution (returned).

Definition at line 346 of file coroutine.h.

◆ ReturnValue()

template<typename ReturnType, typename ArgType>
const ReturnType & COROUTINE< ReturnType, ArgType >::ReturnValue ( ) const
inline

Return the yielded value (the argument KiYield() was called with).

Definition at line 361 of file coroutine.h.

◆ RunMainStack()

template<typename ReturnType, typename ArgType>
void COROUTINE< ReturnType, ArgType >::RunMainStack ( std::function< void()> func)
inline

Run a functor inside the application main stack context.

Call this function for example if the operation will spawn a webkit browser instance which will walk the stack to the upper border of the address space on mac osx systems because its javascript needs garbage collection (for example if you paste text into an edit box).

Definition at line 260 of file coroutine.h.

Referenced by TOOL_MANAGER::RunMainStack().

◆ Running()

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::Running ( ) const
inline

◆ SystemPageSize()

template<typename ReturnType, typename ArgType>
static size_t COROUTINE< ReturnType, ArgType >::SystemPageSize ( )
inlinestaticprivate

The size of the mappable memory page size.

Definition at line 444 of file coroutine.h.

Referenced by COROUTINE< int, int >::doCall().

Member Data Documentation

◆ m_args

template<typename ReturnType, typename ArgType>
std::remove_reference<ArgType>::type* COROUTINE< ReturnType, ArgType >::m_args
private

Pointer to coroutine entry arguments stripped of references to avoid compiler errors.

Definition at line 574 of file coroutine.h.

Referenced by COROUTINE< int, int >::callerStub().

◆ m_callContext

template<typename ReturnType, typename ArgType>
CALL_CONTEXT* COROUTINE< ReturnType, ArgType >::m_callContext
private

Main stack information.

Definition at line 580 of file coroutine.h.

Referenced by COROUTINE< int, int >::Call(), COROUTINE< int, int >::callerStub(), and COROUTINE< int, int >::Resume().

◆ m_callee

template<typename ReturnType, typename ArgType>
CONTEXT_T COROUTINE< ReturnType, ArgType >::m_callee
private

Saved coroutine context.

Definition at line 583 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::RunMainStack().

◆ m_caller

template<typename ReturnType, typename ArgType>
CONTEXT_T COROUTINE< ReturnType, ArgType >::m_caller
private

Saved caller context.

Definition at line 577 of file coroutine.h.

Referenced by COROUTINE< int, int >::callerStub().

◆ m_func

template<typename ReturnType, typename ArgType>
std::function<ReturnType( ArgType )> COROUTINE< ReturnType, ArgType >::m_func
private

Definition at line 569 of file coroutine.h.

Referenced by COROUTINE< int, int >::callerStub().

◆ m_retVal

template<typename ReturnType, typename ArgType>
ReturnType COROUTINE< ReturnType, ArgType >::m_retVal
private

Definition at line 585 of file coroutine.h.

Referenced by COROUTINE< int, int >::callerStub().

◆ m_running

template<typename ReturnType, typename ArgType>
bool COROUTINE< ReturnType, ArgType >::m_running
private

Definition at line 571 of file coroutine.h.

Referenced by COROUTINE< int, int >::callerStub().

◆ m_stack

template<typename ReturnType, typename ArgType>
std::unique_ptr<char[], struct STACK_DELETER> COROUTINE< ReturnType, ArgType >::m_stack
private

Coroutine stack.

Definition at line 564 of file coroutine.h.

◆ m_stacksize

template<typename ReturnType, typename ArgType>
int COROUTINE< ReturnType, ArgType >::m_stacksize
private

Definition at line 567 of file coroutine.h.


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