 |
OS
v7.3.3
Documentation
|
|
OS
v7.3.3
Documentation
|
API interface for the Co-Routines extension. More...
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. | |
| #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. | |
| #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. | |
| #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. | |
| #define | qCR_Restart |
| This statement cause the running Coroutine to restart its execution at the place of the qCR_Begin statement. | |
| #define | qCR_WaitUntil(bCondition) |
| Yields until the logical condition being true. | |
| #define | qCR_TimedWaitUntil(bCondition, tValue) |
| Yields until the logical condition being true or the specified timeout expires. | |
| #define | qCR_Do |
| This statement start a blocking Job segment. | |
| #define | qCR_Until(bCondition) |
| This statement ends a blocking Job segment starting with the qCR_Do statement. | |
| #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". | |
| #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. | |
| #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. | |
| #define | qCR_PositionGet(p) |
| Labels the current position and saves it to p so it can be later restored by qCR_PositionRestore. | |
| #define | qCR_PositionRestore(p) |
| Restores the Co-Routine position saved in p. | |
| #define | qCR_PositionReset(p) |
| Resets the p variable to the beginning of the Co-Routine. | |
| #define | qCR_Delay(tValue) |
| Delay a coroutine for a given number of time. | |
| #define | qCR_TimeoutSet(tValue) |
| Set the internal Co-routine timeout to the specified time. | |
| #define | qCR_TimeoutExpired() |
| Check if the internal Co-routine timeout expires. | |
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. | |
API interface for the Co-Routines extension.
| #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.
| #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.
| [in] | handle | The handle of a coroutine (qCR_Handle_t) |
Example:
| #define qCR_Delay | ( | tValue | ) |
Delay a coroutine for a given number of time.
| [in] | tValue | The amount of time (In seconds), that the calling coroutine should yield. |
| #define qCR_Do |
| #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.
Example:
| #define qCR_PositionGet | ( | p | ) |
Labels the current position and saves it to p so it can be later restored by qCR_PositionRestore.
| [out] | p | The variable of type qCR_Position_t where the current position will be saved. |
| #define qCR_PositionReset | ( | p | ) |
Resets the p variable to the beginning of the Co-Routine.
| [in,out] | p | The variable of type qCR_Position_t to reset. |
| #define qCR_PositionRestore | ( | p | ) |
Restores the Co-Routine position saved in p.
| [in,out] | p | The variable of type qCR_Position_t that contains the position to be restored. |
| #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]
| #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".
| [in] | pSem | A pointer to the semaphore instance (qCR_Semaphore_t) |
| [in] | sValue | The initial count of the semaphore. |
| #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.
| [in] | pSem | A pointer to the qCR_Semaphore_t object in which the operation is executed |
| #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.
| [in] | pSem | A pointer to the qCR_Semaphore_t object in which the operation is executed |
| #define qCR_TimedWaitUntil | ( | bCondition, | |
| tValue ) |
Yields until the logical condition being true or the specified timeout expires.
| [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] * } * |
| #define qCR_TimeoutExpired | ( | ) |
| #define qCR_TimeoutSet | ( | tValue | ) |
Set the internal Co-routine timeout to the specified time.
| tValue | The specific amount of time to wait given in seconds. |
| #define qCR_Until | ( | bCondition | ) |
This statement ends a blocking Job segment starting with the qCR_Do statement.
| [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) |
| #define qCR_WaitUntil | ( | bCondition | ) |
Yields until the logical condition being true.
| [in] | bCondition | The logical condition to be evaluated * Action sequence : [Save progress]
* IF ( condition == False ) {
* [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]
| 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. |
| 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.
| [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. |
1.12.0