ChorusOS man pages section 2K: Kernel System Calls

threadScheduler(2K)

NAME

threadScheduler- get, or set thread scheduling parameters

SYNOPSIS

#include <exec/chExec.h>
#include <sched/chSched.h>
#include <sched/chFifo.h>
#include <sched/chRr.h>
#include <sched/chRt.h>

actorcap

threadli

oldpara

newparam

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

SCHED_FIFO, SCHED_CLASS

DESCRIPTION

threadScheduler() returns and optionally modifies the scheduling parameters of the thread whose local identifier is threadli in the actor whose capability is actorcap. If actorcap is K_MYACTOR, the thread must belong to the current actor. In this case, if threadli is K_MYSELF, the current thread is affected.

oldparam and newparam point to descriptors of old and new scheduling parameters respectively. The type of the descriptor depends on the scheduler. Generally, there is one type of scheduling parameter per scheduling policy (scheduling class) implemented by the scheduler.

Two priority-based schedulers are currently supported: SCHED_FIFO and SCHED_CLASS. The SCHED_FIFO scheduler implements the CLASS_FIFO scheduling policy, which manages parameters of type KnFifoThParms. The SCHED_CLASS scheduler implements the CLASS_FIFO, CLASS_RR and CLASS_RT scheduling policies, which respectively manage parameters of type KnFifoThParms, KnRrThParms and KnRtThParms. The SCHED_CLASS also implements the CLASS_TS that is reserved and should not be used. These policies, as well as the corresponding parameter structures, are described in specific sections below.

If oldparam is not NULL, the thread's current scheduling parameters are stored in the area pointed to by oldparam in the caller's address space.

If newparam is not NULL, it points to an area in the caller's address space containing the new scheduling parameters.

In addition, threadScheduler() as well as the two available schedulers, support the notion of a default scheduling class, which defines a normalized scheduling parameters structure, KnThreadDefaultSched. newparms can point to a variable of this type. The KnThreadDefaultSched structure contains the following fields:

KnSchedClass            tdClass ;
KnThreadPriority        tdPriority ;

where tdClass must equal K_SCHED_DEFAULT. tdPriority establishes the priority of the thread, which may vary between K_PRIOMAX (highest priority) and K_PRIOMIN (lowest priority). The two available schedulers currently map this (virtual) default scheduling class to the CLASS_FIFO policy. This means, in particular, that they interprete the KnThreadDefaultSched priority field in the same way that the CLASS_FIFO interprets the priority field of a KnFifoThParms structure.

CLASS_FIFO

The CLASS_FIFO scheduling class implements a pure priority-based, preemptive, FIFO policy. A thread's scheduling parameters are defined by the KnFifoThParms structure, whose members include the following:

KnSchedClass    fifoClass ;
KnFifoPriority  fifoPriority ;

fifoClass must equal K_SCHED_FIFO. fifoPriority defines the priority of the thread, which may vary between K_FIFO_PRIOMAX (0, highest priority) and K_FIFO_PRIOMIN (255, lowest priority).

CLASS_FIFO uses the full range of priorities (256) in both the SCHED_FIFO and SCHED_CLASS schedulers.

A thread which becomes ready to run after being blocked is always inserted last at the end of its priority ready queue (FIFO policy). This means that a running thread is only preempted if a thread of strictly the highest priority becomes ready to run. A preempted thread is placed at the head of its priority ready queue. This means that it will be elected first when the preempting thread completes or is blocked.

CLASS_RR

The CLASS_RR scheduling class is only available within the SCHED_CLASS scheduler. It implements a priority-based, preemptive, round-robin policy. A thread's scheduling parameters are defined by the KnRrThParms structure, whose members are the following:

KnSchedClass    rrClass ;
KnRrPriority    rrPriority ;

rrClass must be equal to K_SCHED_RR. rrPriority defines the priority of the thread, which may vary between K_RR_PRIOMAX (0, highest priority) and K_RR_PRIOMIN (255, lowest priority).

CLASS_RR uses the full range of priorities (256) of the SCHED_CLASS scheduler.

The SCHED_RR policy is similar to the SCHED_FIFO policy, except that an elected thread is given a fixed time quantum. If the thread is still running at quantum expiration, it is placed at the end of its priority ready queue, and then may be preempted by threads of equal priority. The thread's quantum is reset when the thread becomes ready after being blocked. It is not reset when the thread is elected again after a preemption.

The time quantum is the same for all priority levels and all threads. It is defined by the K_RR_QUANTUM value (100 milliseconds).

CLASS_RT

The CLASS_RT scheduling class is only available within the SCHED_CLASS scheduler. It implements the same policy as the real-time class of UNIX SVR4.0. Refer to the priocntl() manual entry of UNIX SVR4.0 for a complete description.

This policy is basically a round-robin policy, with per thread time quanta.

A thread's scheduling parameters are defined by the KnRtThParms structure, the members of which are the following:

KnSchedClass    rtClass ;
KnRtParms       *rtParms ;

rtClass must be equal to K_SCHED_RT.

The actual parameters are defined by the KnRtParms structure, the members of which are the following:

KnRtPriority    rtPriority ;
unsigned long   rtQSecs ;
long            rtQNSecs ;

The fields of this structure map the fields of the rtparms_t of UNIX SVR4. rtPriority defines the priority of the thread, which may vary between K_RT_PRIOMAX (159, highest priority) and K_RT_PRIOMIN (100, lowest priority). Note that the order of priorities is inverted compared to the CLASS_FIFO priorities. CLASS_RT uses only a sub-range of the SCHED_CLASS priorities. This sub-range corresponds to the range [96, 155] of CLASS_FIFO and CLASS_RR.

rtQSecs and rtQNsecs define the thread's time quantum, respectively in seconds and nanoseconds.

The rtQNsecs field can take the following special values:

RT_SAMEQUANTUM

The thread's quantum must not be modified or, if the thread enters the CLASS_RT class, the thread's quantum is set to the RT_INFINITE quantum.

RT_INFINITE

The thread's time quantum is infinite.

RT_DEFAULT

The thread's time quantum is set to the default for the thread's priority, as follows:

K_RT_PRIOMIN to K_RT_PRIOMIN+9	100 ticks
K_RT_PRIOMIN+10 to K_RT_PRIOMIN+19	80 ticks
K_RT_PRIOMIN+20 to K_RT_PRIOMIN+29	60 ticks
K_RT_PRIOMIN+30 to K_RT_PRIOMIN+39	40 ticks
K_RT_PRIOMIN+40 to K_RT_PRIOMIN+49	20 ticks
K_RT_PRIOMIN+50 to K_RT_PRIOMIN+59	10 ticks

The default tick period is 10ms. In this case, the values in the table should be multiplied by ten in order to get the quantum in ms.

The CLASS_RT manages per configurable priority default time quanta.

CLASS_TS

The CLASS_TS scheduling class is reserved and implements the same policy as the time-sharing class of UNIX SVR4.0.

NOTE

Due to the way the inheritance protocol is implemented, if the priority of the blocked thread is lowered, then the new priority is not inherited by the mutex holder. Consequently, if the priority of a thread blocked on the mutex is raised before being lowered, the mutex holder keeps executing at the highest priority it has ever inherited.

RETURN VALUE

On successful completion, K_OK is returned. Otherwise, a negative error code is returned.

ERRORS

K_EINVAL: actorcap is an inconsistent actor capability.
K_EUNKNOWN: actorcap does not specify a reachable actor.
K_EINVAL: newparam points to a structure containing invalid scheduling parameters.
K_ENOMEM: The system is out of resources.
K_ENOTIMP: newparm specifies a non-supported scheduling policy.
K_EFAULT: Some of the provided data are outside the current actor's address space.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving