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

Collaboration diagram for Co-Routines:

Data Structures
struct	qCR_Semaphore_t
	A typedef to instantiate a Co-Routine Semaphore. More...

Macros
#define	qCR_Position_t
	A typedef to hold Co-Routine current position or progress.

#define	qCR_Begin
	Defines a Coroutine segment. The qCR_Begin 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. qCR_End declare the end of the Coroutine. More...

#define	qCR_BeginWithHandle(handle)
	Defines a Coroutine segment with a supplied external handle. The qCR_BeginWithHandle 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. qCR_End declare the end of the Coroutine. More...

#define	qCR_End
	Ends a Coroutine segment. Only one segment is allowed inside a task. The qCR_End statement is used to define the ending point of a Coroutine. It should be placed at the end of the function in which the Coroutine runs. More...

#define	qCR_Yield
	This statement is only allowed inside a Coroutine segment. qCR_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 qCR_Yield statement. More...

#define	qCR_Restart
	This statement cause the running Coroutine to restart its execution at the place of the qCR_Begin statement. More...

#define	qCR_WaitUntil(bCondition)
	Yields until the logical condition being true. More...

#define	qCR_TimedWaitUntil(bCondition, tValue)
	Yields until the logical condition being true or the specified timeout expires. More...

#define	qCR_Do
	This statement start a blocking Job segment. More...

#define	qCR_Until(bCondition)
	This statement ends a blocking Job segment starting with the qCR_Do statement. More...

#define	qCR_SemInit(pSem, sValue)
	Initializes a semaphore with a value for the counter. Internally, the semaphores use an "unsigned int" to represent the counter, therefore the sValue argument should be within range of an "unsigned int". More...

#define	qCR_SemWait(pSem)
	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. More...

#define	qCR_SemSignal(pSem)
	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. More...

#define	qCR_PositionGet(p)
	Labels the current position and saves it to p so it can be later restored by qCR_PositionRestore. More...

#define	qCR_PositionRestore(p)
	Restores the Co-Routine position saved in p. More...

#define	qCR_PositionReset(p)
	Resets the p variable to the beginning of the Co-Routine. More...

#define	qCR_Delay(tValue)
	Delay a coroutine for a given number of time. More...

#define	qCR_TimeoutSet(tValue)
	Set the internal Co-routine timeout to the specified time. More...

#define	qCR_TimeoutExpired()
	Check if the internal Co-routine timeout expires. More...

Typedefs
typedef _qCR_Instance_t *	qCR_Handle_t
	A typedef to instantiate a Co-Routine handle.

Enumerations
enum	qCR_ExternAction_t { qCR_RESTART , qCR_POSITION_SET , qCR_SUSPEND , qCR_RESUME }
	An enumeration to define the possible actions that can be performed outside the context of a Co-Routine. More...

Functions
qBool_t	qCR_ExternControl (qCR_Handle_t h, const qCR_ExternAction_t action, const qCR_ExtPosition_t pos)
	Perform an external action over the requested Co-routine. More...

Detailed Description

API interface for the Co-Routines extension.

Macro Definition Documentation

◆ qCR_Begin

#define qCR_Begin

Defines a Coroutine segment. The qCR_Begin 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. qCR_End declare the end of the Coroutine.

See also: qCR_End

Warning: Only one segment is allowed inside a task.

Note: It must always be used together with a matching qCR_End statement. Example:
qCR_Begin{

}qCR_End;

qCR_End
#define qCR_End
Ends a Coroutine segment. Only one segment is allowed inside a task. The qCR_End statement is used to...
Definition: qcoroutine.h:259

qCR_Begin
#define qCR_Begin
Defines a Coroutine segment. The qCR_Begin statement is used to declare the starting point of a Corou...
Definition: qcoroutine.h:222

◆ qCR_BeginWithHandle

#define qCR_BeginWithHandle ( handle )

Defines a Coroutine segment with a supplied external handle. The qCR_BeginWithHandle 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. qCR_End declare the end of the Coroutine.

See also: qCR_End

Warning: Only one segment is allowed inside a task.

Note: It must always be used together with a matching qCR_End statement.

Parameters

[in] handle The handle of a coroutine (qCR_Handle_t)

Example:

qCR_BeginWithHandle( handle ) {
 
}qCR_End;

◆ qCR_Delay

#define qCR_Delay ( tValue )

Delay a coroutine for a given number of time.

Parameters

[in] tValue The amount of time (In seconds), that the calling coroutine should yield.

Returns: none.

◆ qCR_Do

#define qCR_Do

This statement start a blocking Job segment.

See also: qCR_Until

Note: Must be used together with a matching qCR_Until statement. Example:
qCR_Do{

}qCR_Until( Condition );

qCR_Do
#define qCR_Do
This statement start a blocking Job segment.
Definition: qcoroutine.h:317

qCR_Until
#define qCR_Until(bCondition)
This statement ends a blocking Job segment starting with the qCR_Do statement.
Definition: qcoroutine.h:334

◆ qCR_End

#define qCR_End

Ends a Coroutine segment. Only one segment is allowed inside a task. The qCR_End statement is used to define the ending point of a Coroutine. It should be placed at the end of the function in which the Coroutine runs.

See also: qCR_Begin; qCR_BeginWithHandle

Note: It must always be used together with a matching qCR_Begin or a qCR_BeginWithHandle statement.

Example:

qCR_Begin{
 
}qCR_End;

◆ qCR_PositionGet

#define qCR_PositionGet ( p )

Labels the current position and saves it to p so it can be later restored by qCR_PositionRestore.

See also: qCR_PositionRestore; qCR_PositionReset

Parameters

[out] p The variable of type qCR_Position_t where the current position will be saved.

Returns: none.

◆ qCR_PositionReset

#define qCR_PositionReset ( p )

Resets the p variable to the beginning of the Co-Routine.

See also: qCR_PositionGet; qCR_PositionRestore

Parameters

[in,out] p The variable of type qCR_Position_t to reset.

Returns: none.

◆ qCR_PositionRestore

#define qCR_PositionRestore ( p )

Restores the Co-Routine position saved in p.

See also: qCR_PositionGet; qCR_PositionReset

Parameters

[in,out] p The variable of type qCR_Position_t that contains the position to be restored.

Returns: none.

◆ qCR_Restart

#define qCR_Restart

This statement cause the running Coroutine to restart its execution at the place of the qCR_Begin statement.

Action sequence : [Reload progress] then [Yield]

◆ qCR_SemInit

#define qCR_SemInit	(	pSem,
		sValue
	)

Initializes a semaphore with a value for the counter. Internally, the semaphores use an "unsigned int" to represent the counter, therefore the sValue argument should be within range of an "unsigned int".

See also: qCR_SemWait; qCR_SemSignal

Parameters

[in]	pSem	A pointer to the semaphore instance (qCR_Semaphore_t)
[in]	sValue	The initial count of the semaphore.

Returns: none.

◆ qCR_SemSignal

#define qCR_SemSignal ( pSem )

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: qCR_SemInit; qCR_SemWait

Parameters

[in] pSem A pointer to the qCR_Semaphore_t object in which the operation is executed

Returns: none.

◆ qCR_SemWait

#define qCR_SemWait ( pSem )

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: qCR_SemInit; qCR_SemSignal

Parameters

[in] pSem A pointer to the qCR_Semaphore_t object in which the operation is executed

Returns: none.

◆ qCR_TimedWaitUntil

#define qCR_TimedWaitUntil	(	bCondition,
		tValue
	)

Yields until the logical condition being true or the specified timeout expires.

See also: qCR_WaitUntil

Parameters

[in]	bCondition	The logical condition to be evaluated.
[in]	tValue	The specific amount of time to wait given in seconds. * Action sequence : [Save progress] * IF ( condition == False \|\| NOT_EXPIRED(timeout) ) * [Yield] * } *

◆ qCR_TimeoutExpired

#define qCR_TimeoutExpired ( )

Check if the internal Co-routine timeout expires.

Returns: qTrue when STimer expires, otherwise, returns qFalse.

◆ qCR_TimeoutSet

#define qCR_TimeoutSet ( tValue )

Set the internal Co-routine timeout to the specified time.

Parameters

tValue The specific amount of time to wait given in seconds.

Returns: none.

◆ qCR_Until

#define qCR_Until ( bCondition )

This statement ends a blocking Job segment starting with the qCR_Do statement.

See also: qCR_Do

Parameters

[in] bCondition 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 qCR_Do statement. Example:
qCR_Do{

}qCR_Until( Condition );

◆ qCR_WaitUntil

#define qCR_WaitUntil ( bCondition )

Yields until the logical condition being true.

See also: qCR_TimedWaitUntil

Parameters

[in]

bCondition

The logical condition to be evaluated

* Action sequence : [Save progress]
*                 IF ( condition == False ) {
*                     [Yield]
*                 }
*

◆ qCR_Yield

#define qCR_Yield

This statement is only allowed inside a Coroutine segment. qCR_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 qCR_Yield statement.

Action sequence : [Save progress] then [Yield]

Enumeration Type Documentation

◆ qCR_ExternAction_t

enum qCR_ExternAction_t

An enumeration to define the possible actions that can be performed outside the context of a Co-Routine.

Enumerator
qCR_RESTART	Restart the coroutine execution at the place of the qCR_BeginWithHandle statement.
qCR_POSITION_SET	Force the coroutine execution at the position specified in qCR_ExternControl(). If a non-valid position is supplied, the Co-routine segment will be suspended.
qCR_SUSPEND	Suspend the entire coroutine segment. The task will still running instructions outside the segment.
qCR_RESUME	Resume the entire coroutine segment at the point where it had been left before the suspension.

Function Documentation

◆ qCR_ExternControl()

qBool_t qCR_ExternControl	(	qCR_Handle_t	h,
		const qCR_ExternAction_t	action,
		const qCR_ExtPosition_t	pos
	)

Perform an external action over the requested Co-routine.

See also: qCR_BeginWithHandle

Parameters

[in]	h	The Co-routine handle.
[in]	action	The specific action to perform, should be one of the following: qCR_RESTART, qCR_SUSPEND, qCR_RESUME or qCR_POSITION_SET.
[in]	pos	The required position if action = qCR_POSITION_SET. For other actions this argument its ignored.

Returns: qTrue on success, otherwise returns qFalse.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ qCR_Begin

◆ qCR_BeginWithHandle

◆ qCR_Delay

◆ qCR_Do

◆ qCR_End

◆ qCR_PositionGet

◆ qCR_PositionReset

◆ qCR_PositionRestore

◆ qCR_Restart

◆ qCR_SemInit

◆ qCR_SemSignal

◆ qCR_SemWait

◆ qCR_TimedWaitUntil

◆ qCR_TimeoutExpired

◆ qCR_TimeoutSet

◆ qCR_Until

◆ qCR_WaitUntil

◆ qCR_Yield

Enumeration Type Documentation

◆ qCR_ExternAction_t

Function Documentation

◆ qCR_ExternControl()