chg_pri

ichg_pri

Outline

Change task priority.

C format

 ER      chg_pri (ID tskid, PRI tskpri);

 ER      ichg_pri (ID tskid, PRI tskpri);

Parameter(s)

I/O	Parameter	Description
I	ID tskid;	ID number of the task. TSK_SELF: Invoking task. Value: ID number of the task.
I	PRI tskpri;	New base priority of the task. TPRI_INI: Initial priority. Value: New base priority of the task.

Explanation

This service call changes the base priority of the task specified by parameter tskid to a value specified by parameter tskpri.

The changed base priority is effective until the task terminates or this service call is issued. When next the task is activated, the base priority is the initial priority which is specified at the task creation.

This service call also changes the current priority of the target task to a value specified by parameter tskpri. However, the current priority is not changed when the target task has locked mutexes.

If the target task has locked mutexes or is waiting for mutex to be locked and if tskpri is higher than the ceiling priority of either of the mutexes, this service call returns "E_ILUSE".

When the current priority is changed, the following state variations are generated.

1 ) When the target task is in the RUNNING or READY state.
This service call re-queues the task at the end of the ready queue corresponding to the priority specified by parameter tskpri.

2 ) When the target task is queued to a wait queue of the object with TA_TPRI or TA_CEILING attribute.
This service call re-queues the task to the wait queue corresponding to the priority specified by parameter tskpri. When two or more tasks of same current priority as tskpri, this service call re-queues the target task at the end among their tasks.

Example When three tasks (task A: priority level 10, task B: priority level 11, task C: priority level 12) are queued to the semaphore wait queue in the order of priority, and the priority level of task B is changed from 11 to 9, the wait order will be changed as follows.

Note For current priority and base priority, refer to "8.2.2 Current priority and base priority".

Return value

Macro	Value	Description
E_OK	0	Normal completion.
E_PAR	-17	Parameter error. - tskpri < 0 - tskpri > TMAX_TPRI
E_ID	-18	Invalid ID number. - tskid < 0 - tskid > VTMAX_TSK - When ichg_pri was issued from a non-task, TSK_SELF was specified for tskid.
E_CTX	-25	Context error. - This service call was issued in the CPU locked state. - The ichg_pri was issued from task. - The chg_pri was issued from non-task. - This service call was issued in the status "PSW.IPL > kernel interrupt mask level".
E_MACV	-26	Memory access violation. (only for chg_pri) - Stack pointer points out of user stack for invoking task.
E_ILUSE	-28	Illegal use of service call. - tskpri < The ceiling priority of the mutex locked by the target task. - tskpri < The ceiling priority of the mutex by which the target task waits for lock.
E_OBJ	-41	Object state error. - Specified task is in the DORMANT state.
E_NOEXS	-42	Non-existent object. - The task specified by tskid does not exist.