tk_sus_tsk
Suspend Task
ER ercd = tk_sus_tsk ( ID tskid ) ;
ID tskid Task ID
ER ercd Error code
E_OK Normal completion
E_ID Invalid ID number (tskid is invalid or cannot be used)
E_NOEXS Object does not exist (the task specified in tskid does not exist)
E_OBJ Invalid object state (called for the invoking task or for a task in DORMANT state)
E_CTX A task in RUN state was specified in dispatch disabled state
E_QOVR Queuing or nesting overflow (too many nested requests in suscnt)
Puts the task specified in tskid in SUSPEND state and interrupts execution by the task.
SUSPEND state is released by issuing system call tk_rsm_tsk or tk_frsm_tsk.
If tk_sus_tsk is called for a task already in WAIT state, the state goes to a combination of WAIT state and SUSPEND state (WAIT-SUSPEND state). Thereafter when the task wait release conditions are met, the task goes to SUSPEND state. If tk_rsm_tsk is issued for the task in WAIT-SUSPEND state,
the task state reverts to WAIT state.
Since SUSPEND state means task interruption by a system call issued by another task, this system call cannot be issued for the invoking task. If the invoking task is specified, error code E_OBJ is returned.
When this system call is issued from a task-independent portion, if a task in RUN state is specified while dispatching is disabled, error code E_CTX is returned.
If tk_sus_tsk is issued more than once for the same task, the task is put in SUSPEND state multiple times. This is called nesting of suspend requests. In this case, the task reverts to its original state only when tk_rsm_tsk has been issued for the same number of times as tk_sus_tsk (suscnt). Accordingly, nesting of the pair tk_sus_tsk . tk_rsm_tsk is possible.
The nesting of suspend requests (issuing tk_sus_tsk two or more times for the same task) and limits
on nesting count are implementation-dependent.
If tk_sus_tsk is issued multiple times in a system that does not allow suspend request nesting, or if the nesting count exceeds the allowed limit, error code E_QOVR is returned.
When a task is in WAIT state for resource acquisition (semaphore wait, etc.) and is also in SUSPEND state, the resource allocation (semaphore allocation, etc.) takes place under the same conditions as when the task is not in SUSPEND state. Resource allocation is not delayed by the SUSPEND state, and there is no change whatsoever in the priority of resource allocation or release from WAIT state. In this way SUSPEND state is in an orthogonal relation with other processing and task states.
In order to delay resource allocation to a task in SUSPEND state (temporarily lower its priority), the user can employ tk_sus_tsk and tk_rsm_tsk in combination with tk_chg_pri.
Task suspension is intended only for very limited uses closely related to the OS, such as page fault processing in a virtual memory system or breakpoint processing in a debugger. As a rule it should not be used in ordinary applications or in middleware.
The reason is that task suspension takes place regardless of the target task running state. If, for example, a task is put in SUSPEND state while it is calling a middleware function, the task will be stopped in the course of middleware internal processing. In some cases middleware performs resource management or other mutual exclusion control. If a task stops inside middleware while it has resources allocated, other tasks may not be able to use that middleware. This situation can cause a chain reactions, with other tasks stopping and leading to system-wide deadlock.
For this reason a task must not be stopped without knowing its status (what it is doing at the time), and ordinary tasks should not use the task suspension function.
Comments