KiCad PCB EDA Suite
Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
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_ARGS * doCall (INVOCATION_ARGS *aInvArgs, ArgType aArgs)
 
INVOCATION_ARGS * doResume (INVOCATION_ARGS *args)
 
INVOCATION_ARGS * jumpIn (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_DELETER > m_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_CONTEXT * m_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 113 of file coroutine.h.

Constructor & Destructor Documentation

◆ COROUTINE() [1/3]

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

Definition at line 233 of file coroutine.h.

◆ COROUTINE() [2/3]

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

Create a coroutine from a member method of an object.

Definition at line 242 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 250 of file coroutine.h.

References ADVANCED_CFG::GetCfg(), ADVANCED_CFG::m_CoroutineStackSize, and COROUTINE< ReturnType, ArgType >::m_stacksize.

◆ ~COROUTINE()

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

Definition at line 265 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::CONTEXT_T::ctx, COROUTINE< ReturnType, ArgType >::m_callee, and COROUTINE< ReturnType, ArgType >::m_caller.

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 322 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::Continue(), COROUTINE< ReturnType, ArgType >::doCall(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, kicadTraceCoroutineStack, and COROUTINE< ReturnType, ArgType >::Running().

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 342 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::doCall(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROUTINE, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_callContext, and COROUTINE< ReturnType, ArgType >::Running().

◆ callerStub()

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

Definition at line 584 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::context, COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::destination, COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, COROUTINE< ReturnType, ArgType >::jumpOut(), COROUTINE< ReturnType, ArgType >::m_args, COROUTINE< ReturnType, ArgType >::m_callContext, COROUTINE< ReturnType, ArgType >::m_caller, COROUTINE< ReturnType, ArgType >::m_func, COROUTINE< ReturnType, ArgType >::m_retVal, COROUTINE< ReturnType, ArgType >::m_running, COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::SetMainStack(), and COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::type.

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

◆ doCall()

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

Definition at line 411 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::CONTEXT_T::ctx, COROUTINE< ReturnType, ArgType >::GuardMemory(), COROUTINE< ReturnType, ArgType >::jumpIn(), kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_args, COROUTINE< ReturnType, ArgType >::m_callee, COROUTINE< ReturnType, ArgType >::m_caller, COROUTINE< ReturnType, ArgType >::m_func, COROUTINE< ReturnType, ArgType >::m_running, COROUTINE< ReturnType, ArgType >::m_stack, COROUTINE< ReturnType, ArgType >::m_stacksize, COROUTINE< ReturnType, ArgType >::MapMemory(), and COROUTINE< ReturnType, ArgType >::SystemPageSize().

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

◆ doResume()

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

Definition at line 563 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::jumpIn(), and COROUTINE< ReturnType, ArgType >::m_caller.

Referenced by COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::Continue(), and COROUTINE< ReturnType, ArgType >::Resume().

◆ 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 549 of file coroutine.h.

References kicadTraceCoroutineStack, and res.

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

◆ jumpIn()

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

Definition at line 603 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::CONTEXT_T::ctx, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_callee, and COROUTINE< ReturnType, ArgType >::m_caller.

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

◆ jumpOut()

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

Definition at line 641 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::context, COROUTINE< ReturnType, ArgType >::CONTEXT_T::ctx, COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROUTINE, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_callContext, COROUTINE< ReturnType, ArgType >::m_callee, COROUTINE< ReturnType, ArgType >::m_caller, COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::SetMainStack(), and COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::type.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), and COROUTINE< ReturnType, ArgType >::KiYield().

◆ 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 285 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::jumpOut().

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 295 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::jumpOut(), and COROUTINE< ReturnType, ArgType >::m_retVal.

◆ 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 532 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::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 362 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::Continue(), COROUTINE< ReturnType, ArgType >::doResume(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, kicadTraceCoroutineStack, and COROUTINE< ReturnType, ArgType >::Running().

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 382 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::doResume(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROUTINE, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_callContext, and COROUTINE< ReturnType, ArgType >::Running().

◆ 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 397 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::m_retVal.

◆ 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 308 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::m_callContext, and COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::RunMainStack().

Referenced by TOOL_MANAGER::RunMainStack().

◆ Running()

template<typename ReturnType , typename ArgType >
bool COROUTINE< ReturnType, ArgType >::Running ( ) const
inline
Returns
true if the coroutine is active.

Definition at line 405 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::m_running.

Referenced by COROUTINE< ReturnType, ArgType >::Call(), TOOL_MANAGER::dispatchInternal(), and COROUTINE< ReturnType, ArgType >::Resume().

◆ 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 512 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::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 716 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), and COROUTINE< ReturnType, ArgType >::doCall().

◆ m_callContext

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

Main stack information.

Definition at line 722 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::Call(), COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::jumpOut(), COROUTINE< ReturnType, ArgType >::Resume(), and COROUTINE< ReturnType, ArgType >::RunMainStack().

◆ m_callee

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

Saved coroutine context.

Definition at line 725 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::doCall(), COROUTINE< ReturnType, ArgType >::jumpIn(), COROUTINE< ReturnType, ArgType >::jumpOut(), COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::RunMainStack(), and COROUTINE< ReturnType, ArgType >::~COROUTINE().

◆ m_caller

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

Saved caller context.

Definition at line 719 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::doCall(), COROUTINE< ReturnType, ArgType >::doResume(), COROUTINE< ReturnType, ArgType >::jumpIn(), COROUTINE< ReturnType, ArgType >::jumpOut(), and COROUTINE< ReturnType, ArgType >::~COROUTINE().

◆ m_func

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

Definition at line 711 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), and COROUTINE< ReturnType, ArgType >::doCall().

◆ m_retVal

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

Definition at line 727 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::KiYield(), and COROUTINE< ReturnType, ArgType >::ReturnValue().

◆ m_running

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

Definition at line 713 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::doCall(), and COROUTINE< ReturnType, ArgType >::Running().

◆ 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 706 of file coroutine.h.

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

◆ m_stacksize

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

Definition at line 709 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::COROUTINE(), and COROUTINE< ReturnType, ArgType >::doCall().

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