COROUTINE< ReturnType, ArgType > Class Template Reference

Implement a coroutine. More...

#include <coroutine.h>

Classes
class	CALL_CONTEXT
struct	CONTEXT_T
struct	INVOCATION_ARGS

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

Static Private Member Functions
static void	callerStub (intptr_t aData)

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

Constructor & Destructor Documentation

COROUTINE() [1/3]

template<typename ReturnType , typename ArgType >

COROUTINE< ReturnType, ArgType >::COROUTINE ( )

inline

Definition at line 172 of file coroutine.h.

 :
 COROUTINE( nullptr )
 {
 }

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

 :
 COROUTINE( std::bind( ptr, object, std::placeholders::_1 ) )
 {
 }

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

 :
 m_func( std::move( aEntry ) ),
 m_running( false ),
 m_args( nullptr ),
 m_caller(),
 m_callContext( nullptr ),
 m_callee(),
 m_retVal( 0 )
#ifdef KICAD_USE_VALGRIND
 ,m_valgrind_stack( 0 )
#endif
#ifdef KICAD_SANITIZE_ADDRESS
 ,asan_stack( nullptr )
#endif
 {
 m_stacksize = ADVANCED_CFG::GetCfg().m_CoroutineStackSize;
 }

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

 {
#ifdef KICAD_USE_VALGRIND
 VALGRIND_STACK_DEREGISTER( m_valgrind_stack );
#endif
 
 if( m_caller.ctx )
 libcontext::release_fcontext( m_caller.ctx );
 
 if( m_callee.ctx )
 libcontext::release_fcontext( m_callee.ctx );
 }

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

 {
 CALL_CONTEXT ctx;
 INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROOT, this, &ctx };
 
#ifdef KICAD_SANITIZE_THREADS
 // Get the TSAN fiber for the current stack here
 m_caller.tsan_fiber = __tsan_get_current_fiber();
 m_caller.own_tsan_fiber = false;
#endif
 
 wxLogTrace( kicadTraceCoroutineStack, "COROUTINE::Call (from root)" );
 
 ctx.Continue( doCall( &args, aArg ) );
 
 return Running();
 }

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

 {
 INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROUTINE, this, aCor.m_callContext };
 
 wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::Call (from routine)" ) );
 
 doCall( &args, aArg );
 // we will not be asked to continue
 
 return Running();
 }

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

 {
 INVOCATION_ARGS& args = *reinterpret_cast<INVOCATION_ARGS*>( aData );
 
 // get pointer to self
 COROUTINE* cor = args.destination;
 cor->m_callContext = args.context;
 
 if( args.type == INVOCATION_ARGS::FROM_ROOT )
 cor->m_callContext->SetMainStack( &cor->m_caller );
 
 // call the coroutine method
 cor->m_retVal = cor->m_func( *(cor->m_args) );
 cor->m_running = false;
 
 // go back to wherever we came from.
 cor->jumpOut();
 }

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

 {
 assert( m_func );
 assert( !( m_callee.ctx ) );
 
 m_args = &aArgs;
 
 assert( m_stack == nullptr );
 
 size_t stackSize = m_stacksize;
 void* sp = nullptr;
 
#ifndef LIBCONTEXT_HAS_OWN_STACK
 
 // fixme: Clean up stack stuff. Add a guard
 m_stack.reset( new char[stackSize] );
 
 // align to 16 bytes
 sp = (void*)((((ptrdiff_t) m_stack.get()) + stackSize - 0xf) & (~0x0f));
 
 // correct the stack size
 stackSize -= size_t( ( (ptrdiff_t) m_stack.get() + stackSize ) - (ptrdiff_t) sp );
 
#ifdef KICAD_USE_VALGRIND
 m_valgrind_stack = VALGRIND_STACK_REGISTER( sp, m_stack.get() );
#endif
#endif
 
#ifdef KICAD_SANITIZE_THREADS
 // Create a new fiber to go with the new context
 m_callee.tsan_fiber = __tsan_create_fiber( 0 );
 m_callee.own_tsan_fiber = true;
 
 __tsan_set_fiber_name( m_callee.tsan_fiber, "Coroutine fiber" );
#endif
 
 wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::doCall" ) );
 
 m_callee.ctx = libcontext::make_fcontext( sp, stackSize, callerStub );
 m_running = true;
 
 // off we go!
 return jumpIn( aInvArgs );
 }

References COROUTINE< ReturnType, ArgType >::callerStub(), COROUTINE< ReturnType, ArgType >::CONTEXT_T::ctx, 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, and COROUTINE< ReturnType, ArgType >::m_stacksize.

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

 {
 return jumpIn( args );
 }

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

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

jumpIn()

template<typename ReturnType , typename ArgType >

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

inlineprivate

Definition at line 435 of file coroutine.h.

 {
#ifdef KICAD_SANITIZE_THREADS
 // Tell TSAN we are changing fibers to the callee
 __tsan_switch_to_fiber( m_callee.tsan_fiber, 0 );
#endif
 
 wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::jumpIn" ) );
 
 args = reinterpret_cast<INVOCATION_ARGS*>(
 libcontext::jump_fcontext( &( m_caller.ctx ), m_callee.ctx,
 reinterpret_cast<intptr_t>( args ) )
 );
 
 return args;
 }

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

 {
 jumpOut();
 }

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

 {
 m_retVal = aRetVal;
 jumpOut();
 }

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

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

 {
 CALL_CONTEXT ctx;
 INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROOT, this, &ctx };
 
#ifdef KICAD_SANITIZE_THREADS
 // Get the TSAN fiber for the current stack here
 m_caller.tsan_fiber = __tsan_get_current_fiber();
 m_caller.own_tsan_fiber = false;
#endif
 
 wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::Resume (from root)" ) );
 
 ctx.Continue( doResume( &args ) );
 
 return Running();
 }

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

 {
 INVOCATION_ARGS args{ INVOCATION_ARGS::FROM_ROUTINE, this, aCor.m_callContext };
 
 wxLogTrace( kicadTraceCoroutineStack, wxT( "COROUTINE::Resume (from routine)" ) );
 
 doResume( &args );
 // we will not be asked to continue
 
 return Running();
 }

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

 {
 return m_retVal;
 }

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

 {
 assert( m_callContext );
 m_callContext->RunMainStack( this, std::move( func ) );
 }

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

 {
 return m_running;
 }

References COROUTINE< ReturnType, ArgType >::m_running.

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

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 488 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 494 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 497 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 491 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 482 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 499 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 484 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[]> COROUTINE< ReturnType, ArgType >::m_stack

private

Definition at line 478 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 480 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