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

Constructor & Destructor Documentation

◆ COROUTINE() [1/3]

template<typename ReturnType , typename ArgType >

COROUTINE< ReturnType, ArgType >::COROUTINE ( )

inline

Definition at line 182 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 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.

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 217 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 274 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 300 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 501 of file coroutine.h.

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

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 495 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

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

Definition at line 481 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 520 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 537 of file coroutine.h.

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 237 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 247 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 464 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 320 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 346 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 361 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 260 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 369 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 444 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 574 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 580 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 583 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 577 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 569 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 585 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 571 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 564 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 567 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:

coroutine.h

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ COROUTINE() [1/3]

◆ COROUTINE() [2/3]

◆ COROUTINE() [3/3]

◆ ~COROUTINE()

Member Function Documentation

◆ Call() [1/2]

◆ Call() [2/2]

◆ callerStub()

◆ doCall()

◆ doResume()

◆ GuardMemory()

◆ jumpIn()

◆ jumpOut()

◆ KiYield() [1/2]

◆ KiYield() [2/2]

◆ MapMemory()

◆ Resume() [1/2]

◆ Resume() [2/2]

◆ ReturnValue()

◆ RunMainStack()

◆ Running()

◆ SystemPageSize()

Member Data Documentation

◆ m_args

◆ m_callContext

◆ m_callee

◆ m_caller

◆ m_func

◆ m_retVal

◆ m_running

◆ m_stack

◆ m_stacksize