tk_chg_pri
Change Task Priority
ER ercd = tk_chg_pri ( ID tskid, PRI tskpri ) ;
ID skid ask ID
PRI skpri Task priority
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_PAR Parameter error (tskpri is invalid or cannot be used)
E_ILUSE Illegal use (upper priority limit exceeded)
Changes the base priority of the task specified in tskid to the value specified in tskpri. The current priority of the task also changes as a result.
Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority. When TSK_SELF (= 0) is specified in tskid, the invoking task is the target task. Note, however, that when tskid = TSK_SELF is specified in a system call issued from a task-independent portion, error code E_ID is returned. When TPRI INI (= 0) is specified as tskpri, the target task base priority is changed to the initial priority when the task was started (itskpri).
A priority changed by this system call remains valid until the task is terminated. When the task reverts to DORMANT state, the task priority before its exit is discarded, with the task again assigned to the initial priority when the task was started (itskpri). A priority changed while the task is already in DORMANT state, however, becomes valid, so that the task has the new priority as its initial priority the next time it is started.
If as a result of this system call execution the target task current priority matches the base priority (this condition is always met when the mutex function is not used), processing is as follows. If the target task is in a run state, the task precedence changes according to its priority. The target task has the lowest precedence among tasks of the same priority after the change. If the target task is in some kind of priority-based queue, the order in that queue changes in accord with the new task priority. Among tasks of the same priority after the change, the target task is queued at the end.
If the target task has locked a TA_CEILING attribute mutex or is waiting for a lock, and the base priority specified in tskpri is higher than any of the ceiling priorities, error code E_ILUSE is returned.
In some cases when this system call results in a change in the queued order of the target task in a task priority-based queue, it may be necessary to release the wait state of another task waiting in that queue (in a message buffer send queue, or in a queue waiting to acquire a variable-size memory pool).
In some cases when this system call results in a base priority change while the target task is waiting for a TA_INHERIT attribute mutex lock, dynamic priority inheritance processing may be necessary. When a mutex function is not used and the system call is issued specifying the invoking task as the target task, setting the new priority to the base priority of the invoking task, the order of execution of the invoking task becomes the lowest among tasks of the same priority. This system call can therefore be used to relinquish execution privilege.
Comments