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
 The size of the mappable memory page size. 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)
 A functor that frees the stack.
 
INVOCATION_ARGS * doResume (INVOCATION_ARGS *args)
 
INVOCATION_ARGS * jumpIn (INVOCATION_ARGS *args)
 
void jumpOut ()
 coroutine stack
 

Static Private Member Functions

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

Private Attributes

std::unique_ptr< char[], struct STACK_DELETER > m_stack
 
int m_stacksize
 
std::function< ReturnType(ArgType)> m_func
 
bool m_running
 pointer to coroutine entry arguments.
 
std::remove_reference< ArgType >::type * m_args
 saved caller context
 
CONTEXT_T m_caller
 main stack information
 
CALL_CONTEXT * m_callContext
 saved coroutine context
 
CONTEXT_T m_callee
 
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

Definition at line 180 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 189 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 197 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 215 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 272 of file coroutine.h.

References COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::Continue(), COROUTINE< ReturnType, ArgType >::doCall(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_caller, 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 298 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 497 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

A functor that frees the stack.

Definition at line 373 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_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 491 of file coroutine.h.

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

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

Definition at line 477 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 516 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

coroutine stack

Definition at line 533 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 235 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 245 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

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

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

References COROUTINE< ReturnType, ArgType >::CALL_CONTEXT::Continue(), COROUTINE< ReturnType, ArgType >::doResume(), COROUTINE< ReturnType, ArgType >::INVOCATION_ARGS::FROM_ROOT, kicadTraceCoroutineStack, COROUTINE< ReturnType, ArgType >::m_caller, 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 344 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 359 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 258 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 367 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

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

Definition at line 442 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

saved caller context

Definition at line 571 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

saved coroutine context

Definition at line 577 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

Definition at line 580 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

main stack information

Definition at line 574 of file coroutine.h.

Referenced by COROUTINE< ReturnType, ArgType >::Call(), COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::jumpIn(), COROUTINE< ReturnType, ArgType >::jumpOut(), COROUTINE< ReturnType, ArgType >::Resume(), 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 565 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 582 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

pointer to coroutine entry arguments.

Stripped of references to avoid compiler errors.

Definition at line 567 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

Definition at line 560 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 563 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: