Co-Routines

API interface for the Co-Routines extension. More...

Collaboration diagram for Co-Routines:

Classes
class	qOS::co::position
	A placeholder for the Co-Routine current position or progress. More...
class	qOS::co::handle
	A Co-Routine handle. More...
class	qOS::co::semaphore
	A Co-Routine Semaphore. More...

Typedefs
using	qOS::co::state
	The intrinsic type of co::position to hold a coroutine progress.

Functions
void	qOS::co::reenter (void) noexcept
	Defines a Coroutine segment. The co::reenter() statement is used to declare the starting point of a Coroutine. It should be placed at the start of the function in which the Coroutine runs.
void	qOS::co::reenter (qOS::co::handle h) noexcept
	Defines a Coroutine segment with a supplied external handle. The co::reenter() statement is used to declare the starting point of a Coroutine. It should be placed at the start of the function in which the Coroutine runs.
void	qOS::co::yield (void) noexcept
	This statement is only allowed inside a Coroutine segment. co::yield return the CPU control back to the scheduler but saving the execution progress. With the next task activation, the Coroutine will resume the execution after the last co::yield statement.
void	qOS::co::delay (qOS::duration_t t) noexcept
	Delay a coroutine for a given number of time.
void	qOS::co::waitUntil (bool condition) noexcept
	Yields until the logical condition is met.
void	qOS::co::waitUntil (bool condition, qOS::duration_t timeout) noexcept
	Yields until the logical condition is met or the specified timeout expires.
bool	qOS::co::timeoutExpired (void) noexcept
	Check if the internal Co-routine timeout expires.
void	qOS::co::restart (void) noexcept
	This statement cause the running Coroutine to restart its execution at the place of the co::reenter() statement.
void	qOS::co::semWait (co::semaphore &sem) noexcept
	Carries out the "wait" operation on the semaphore. The wait operation causes the Co-routine to block while the counter is zero. When the counter reaches a value larger than zero, the Coroutine will continue.
void	qOS::co::semSignal (co::semaphore &sem) noexcept
	Carries out the "signal" operation on the semaphore. The signal operation increments the counter inside the semaphore, which eventually will cause waiting Co-routines to continue executing.
void	qOS::co::getPosition (co::position &var) noexcept
	Labels the current position and saves it to var so it can be later restored by co::setPosition()
void	qOS::co::setPosition (co::position &var) noexcept
	Restores the Co-Routine position saved in var.
void	qOS::co::perform (void) noexcept
	This statement start a blocking Job segment.
void	qOS::co::perform (qOS::duration_t t) noexcept
	This statement start a blocking Job segment.
void	qOS::co::until (bool condition) noexcept
	This statement ends a blocking Job segment starting with the co::perform() statement.
void	qOS::co::until (bool condition, qOS::duration_t timeout) noexcept

Detailed Description

API interface for the Co-Routines extension.

Typedef Documentation

state

using qOS::co::state

The intrinsic type of co::position to hold a coroutine progress.

Function Documentation

delay()

void qOS::co::delay ( qOS::duration_t t )

inlinenoexcept

Delay a coroutine for a given number of time.

Parameters

[in]

t

The amount of time that the calling coroutine should yield.

getPosition()

void qOS::co::getPosition ( co::position & var )

inlinenoexcept

Labels the current position and saves it to var so it can be later restored by co::setPosition()

See also

co::setPosition()

Parameters

[out]

var

The variable of type co::position where the current position will be saved.

perform() [1/2]

void qOS::co::perform ( qOS::duration_t t )

inlinenoexcept

This statement start a blocking Job segment.

See also

co::until()

Note

Must be used together with a matching co::until() statement.

Warning

Co-routines statements are not allowed within the job segment. and can produce undefined behavior.

Parameters

[in]

t

The timeout for the specified job segment.

Example:

co::perform( timeout ) {
 
} co::until( Condition );

perform() [2/2]

void qOS::co::perform ( void )

inlinenoexcept

This statement start a blocking Job segment.

See also

co::until()

Note

Must be used together with a matching co::until() statement.

Warning

Co-routines statements are not allowed within the job segment. and can produce undefined behavior.

Example:

co::perform() {
 
} co::until( Condition );

reenter() [1/2]

void qOS::co::reenter ( qOS::co::handle h )

inlinenoexcept

Defines a Coroutine segment with a supplied external handle. The co::reenter() statement is used to declare the starting point of a Coroutine. It should be placed at the start of the function in which the Coroutine runs.

Parameters

[in]

h

The handle of a coroutine.

Warning

Only one segment is allowed inside a task.

Example:

co::reenter( handle ) {
 
}

reenter() [2/2]

void qOS::co::reenter ( void )

inlinenoexcept

Defines a Coroutine segment. The co::reenter() statement is used to declare the starting point of a Coroutine. It should be placed at the start of the function in which the Coroutine runs.

Warning

Only one segment is allowed inside a task.

Example:

co::reenter() {
 
}

restart()

void qOS::co::restart ( void )

inlinenoexcept

This statement cause the running Coroutine to restart its execution at the place of the co::reenter() statement.

Action sequence : [Reload progress] then [Yield] 

semSignal()

void qOS::co::semSignal ( co::semaphore & sem )

inlinenoexcept

Carries out the "signal" operation on the semaphore. The signal operation increments the counter inside the semaphore, which eventually will cause waiting Co-routines to continue executing.

See also

co::semWait()

Parameters

[in]

sem

The co::semaphore object in which the operation is executed

semWait()

void qOS::co::semWait ( co::semaphore & sem )

inlinenoexcept

Carries out the "wait" operation on the semaphore. The wait operation causes the Co-routine to block while the counter is zero. When the counter reaches a value larger than zero, the Coroutine will continue.

See also

co::semSignal()

Parameters

[in]

sem

The co::semaphore object in which the operation is executed

setPosition()

void qOS::co::setPosition ( co::position & var )

inlinenoexcept

Restores the Co-Routine position saved in var.

See also

co::getPosition()

Parameters

[in,out]

var

The variable of type co::position that contains the position to be restored.

timeoutExpired()

bool qOS::co::timeoutExpired ( void )

inlinenoexcept

Check if the internal Co-routine timeout expires.

Returns

true when timer expires, otherwise, returns false. Example:

co::reenter( handle ) {
    co::waitUntil( count > 10 , 5.0f );
    if ( co::timeoutExpired() ) {
        co::restart;
    }
}

until() [1/2]

void qOS::co::until ( bool condition )

inlinenoexcept

This statement ends a blocking Job segment starting with the co::perform() statement.

See also

co::perform()

Parameters

[in]

condition

The logical condition to be evaluated. The condition determines if the blocking job ends (if condition is True) or continue yielding (if false)

Note

Must be used together with a matching co::perform() statement. Example:

co::perform() {
 
} co::until( Condition );

until() [2/2]

void qOS::co::until ( bool condition, qOS::duration_t timeout )

inlinenoexcept

waitUntil() [1/2]

void qOS::co::waitUntil ( bool condition )

inlinenoexcept

Yields until the logical condition is met.

Parameters

[in]

condition

The logical condition to be evaluated. The condition determines if the blocking job ends (if condition is true) or continue yielding (if false) * Action sequence : [Save progress] * IF ( condition == False ) { * [Yield] * } *

waitUntil() [2/2]

void qOS::co::waitUntil ( bool condition, qOS::duration_t timeout )

inlinenoexcept

Yields until the logical condition is met or the specified timeout expires.

Parameters

[in]	condition	The logical condition to be evaluated. The condition determines if the blocking job ends (if condition is true) or continue yielding (if false)
[in]	timeout	The specific amount of time to wait given in milliseconds.. * Action sequence : [Save progress] * IF ( condition == False || NOT_EXPIRED(timeout) ) * [Yield] * } *

yield()

void qOS::co::yield ( void )

inlinenoexcept

This statement is only allowed inside a Coroutine segment. co::yield return the CPU control back to the scheduler but saving the execution progress. With the next task activation, the Coroutine will resume the execution after the last co::yield statement.

Action sequence : [Save progress] then [Yield]