4. Quick reference guide

Function signatures

The following table shows the main function signatures that are required and the context in which they are executed. These functions can represent any callable object such as lambdas or regular functions.

Coroutine task	AsyncIo task
int(CoroContext::Ptr, ...)	int(ThreadPromise::Ptr, ...)

Calling conventions and return types

Main below refers simply to your application's main thread or any other thread outside of the quantum framework.

Method	Instance	Location	Return Type
post()	TaskDispatcher	main	ThreadContext<T>::Ptr
post()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr
postAsyncIo()	TaskDispatcher	main	ThreadPromise<T>::Ptr
postAsyncIo()	CoroContext<T>::Ptr	coroutine	CoroPromise<T>::Ptr
postFirst()	TaskDispatcher	main	ThreadContext<T>::Ptr
postFirst()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr
then()	ThreadContext<T>::Ptr	main	ThreadContext<T>::Ptr
then()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr
onError()	ThreadContext<T>::Ptr	main	ThreadContext<T>::Ptr
onError()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr
finally()	ThreadContext<T>::Ptr	main	ThreadContext<T>::Ptr
finally()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr
end()	ThreadContext<T>::Ptr	main	ThreadContext<T>::Ptr
end()	CoroContext<T>::Ptr	coroutine	CoroContext<T>::Ptr

Note that objects in quantum are named using the location in which they are supposed to be used for disambiguation. As such CoroContext<T>::Ptr can only appear in a coroutine.

Blocking and yielding functions

The following functions block or yield implicitly with the exception of yield() which yields explicitly. Note that ICoroSync is a base class of CoroContext<T> and as such the derived class can be passed directly into the function.

Method	Instance	Location	Action	Requires CoroSync::Ptr as argument
yield()	CoroContext<T>::Ptr	coroutine	yields	yes
getXXX()	ThreadContext<T>::Ptr	main	blocks	no
getXXX()	CoroContext<T>::Ptr	coroutine	yields	yes
set()	ThreadPromise<T>::Ptr	IO thread	blocks(1)	no
set()	CoroContext<T>::Ptr	coroutine	yields(1)	no
push()	ThreadPromise<T>::Ptr	IO thread	blocks(1)(2)	no
push()	CoroContext<T>::Ptr	coroutine	blocks(1)(2)	no
pull()	ThreadContext<T>::Ptr	main	blocks(2)	no
pull()	CoroContext<T>::Ptr	coroutine	yields(2)	yes
waitXXX()	ThreadContext<T>::Ptr	main	blocks	no
waitXXX()	CoroContext<T>::Ptr	coroutine	yields	yes
lock()	Mutex	main	blocks	no
lock()	Mutex	coroutine	yields	yes
waitXXX()	ConditionVariable	main	blocks	no
waitXXX()	ConditionVariable	coroutine	yields	yes

(1) May block for a very small period of time if there is contention on the shared promise/future state. (2) Only applicable to buffered futures.