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.

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.

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.

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:

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