thr_setscheduler(3thread)

thr_setscheduler -- set the scheduling policy for a thread

Synopsis

   cc [options] -Kthread file
   
   #include <thread.h>
   

   int thr_setscheduler(thread_t tid, const sched_param_t *param);

Description

thr_setscheduler sets the scheduling policy and corresponding policy-specific parameters of tid to those specified by the sched_param_t structure pointed to by param.

Example

   sched_param_t s;
   s.policy = SCHED_TS;
   (struct ts_param *) (s.policy_params)->prio = 63;

Parameters

tid: target thread ID
param: pointer to a structure containing scheduling policy parameters to be used

tid parameter

tid is the ID of the thread whose scheduling policy thr_setscheduler will set.

param parameter

param is a pointer to a sched_param_t structure that has been initialized to contain the scheduling policy and corresponding parameters to which tid will be set. The priority of the thread is the only corresponding parameter that can be set.

sched_param_t includes:

   	id_t	policy;
   	long	policy_params[POLICY_PARAM_SZ];

The policy member of sched_param_t can be set to any of the following scheduling policies:

SCHED_TS: Time-sharing scheduling policy. Both bound and multiplexed threads can use SCHED_TS. Multiplexed threads must use the SCHED_TS or the SCHED_OTHER policy.
Bound threads using the SCHED_TS scheduling policy will be bound to an LWP in the kernel time-sharing scheduling class. However, the thread scheduling policy has no effect on the kernel scheduling class of the LWPs in the pool of LWPs used to run multiplexed threads.
SCHED_FIFO: A fixed-priority scheduling policy. Only bound threads can use SCHED_FIFO. Threads scheduled under this policy will run on an LWP in the kernel fixed-priority scheduling class with an infinite time quantum.
SCHED_RR: A fixed-priority scheduling policy. Only bound threads can use SCHED_RR. Threads scheduled under this policy will run on an LWP in the kernel fixed-priority scheduling class with the time quantum returned by thr_get_rr_interval(3thread).
SCHED_OTHER: An alias for SCHED_TS.

policy_params contains the priority to which the thread should be assigned. policy_params can be cast to a pointer to the parameter structure corresponding to the scheduling policy. Each of the parameter structures contains a single member, the integer prio. The parameter structures are:

ts_param: for time-sharing scheduling parameters
fifo_param: for FIFO scheduling parameters
rr_param: for round-robin scheduling parameters

For bound threads, the priority set with thr_setscheduler is passed to the system scheduler; it is not maintained by the Threads Library. For multiplexed threads, the priority set with thr_setscheduler is used by the Threads Library in scheduling multiplexed threads to run on LWPs. The priorities for multiplexed threads remain fixed (unless explicitly changed with thr_setscheduler or thr_setprio), and the Threads Library assigns higher priority threads to LWPs before lower priority threads. Therefore, although multiplexed threads run under the SCHED_TS policy, the scheduling algorithm more closely resembles that of the kernel's fixed-priority scheduling class than it does the kernel's time-sharing scheduling class.

Priority range for multiplexed threads

In this implementation, the priority range for the SCHED_TS policy for multiplexed threads is from zero to MAXINT-1. However, for better performance, we recommend using a maximum priority of 126 or lower. The default priority for multiplexed threads is 63.

In all scheduling policies supported by this implementation, numerically higher values represent higher priorities.

Priority range for bound threads

Bound threads running under any scheduling policy are subject to the priority ranges set by the system. Use priocntl(1) or priocntl(2) to find what scheduling priorities are available on your system.

Security restrictions

No privileges or special permissions are required to use thr_setscheduler to set the policy or priority of a multiplexed thread. Appropriate privilege is required to set the policy of any thread or process to SCHED_FIFO or SCHED_RR. The following rules apply to changing the priority of bound threads:

You can always lower the priority of any bound thread.
You can always raise the priority of bound threads in the SCHED_FIFO and SCHED_RR classes.
You must have privilege to raise the priority of a bound thread in the SCHED_TS class. The required privileges might vary across installations.

Notes

thr_setscheduler for bound threads is implemented as a wrapper around priocntl(2). Therefore, scheduling policy and parameter changes are subject to the restrictions and privileges set by the operating system scheduler. However, bound threads should always use thr_setscheduler instead of calling priocntl directly.

Note that each multiplexed thread run by a lightweight process (LWP) will affect the priority of that LWP in the system scheduler. Over time, there will be approximate balance across the multiplexed threads in a process.

Usage

thr_setscheduler is used by multithreaded applications that need to control their scheduling.

Return values

thr_setscheduler returns zero for success and an error number for failure.

Errors

If any of the following conditions is detected, thr_setscheduler returns the corresponding value:

EINVAL: param points to a structure containing parameters that are invalid for the requested policy.
ENOSYS: tid is multiplexed (not bound to an LWP), and the scheduling policy being set is SCHED_FIFO or SCHED_RR. Multiplexed threads must be SCHED_TS or SCHED_OTHER.
EPERM: The caller does not have appropriate privilege for the operation.
ESRCH: No thread can be found in the current process with ID tid.

References

Intro(3thread), priocntl(1), priocntl(2), thr_create(3thread), thr_getprio(3thread), thr_getscheduler(3thread), thr_setprio(3thread), thr_yield(3thread)