rtsched(2)

NAME

rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() — real-time scheduling operations

SYNOPSIS

#include <sched.h> 

int sched_setparam( 
    pid_t pid, 
    const struct sched_param *param 
); 

int sched_getparam( 
    pid_t pid, 
    struct sched_param *param 
); 

int sched_setscheduler( 
    pid_t pid, 
    int policy, 
    const struct sched_param *param 
); 

int sched_getscheduler( 
    pid_t pid 
); 

int sched_yield(); 

int sched_get_priority_max( 
    int policy 
); 

int sched_get_priority_min( 
    int policy 
); 

int sched_rr_get_interval( 
    pid_t pid, 
    struct timespec *interval 
); 

int PRI_POSIX_TO_HPUX( 
    int pri 
); 

int PRI_HPUX_TO_POSIX( 
    int pri 
); 

DESCRIPTION

Summary

sched_get_priority_max(): Get maximum scheduling policy
sched_get_priority_min(): Get minimum scheduling policy
sched_getparam(): Get scheduling parameters of process
sched_getscheduler(): Get scheduling policy of process
sched_rr_get_interval(): Get execution time limit for a process
sched_setparam(): Set scheduling parameters of process
sched_setscheduler(): Set scheduling policy and parameters of process
sched_yield(): Requeue current thread in thread list
PRI_HPUX_TO_POSIX(): Convert HP-UX priority to POSIX
PRI_POSIX_TO_HPUX(): Convert POSIX priority to HP-UX

sched_setparam()

The sched_setparam() function sets the scheduling parameters of the process specified by pid to the values specified by the sched_param structure pointed to by param. The value of the sched_priority member in the param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by pid.

Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the SCHED_HPUX, SCHED_TIMESHARE, SCHED_NOAGE, and SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the PRI_HPUX_TO_POSIX() and PRI_POSIX_TO_HPUX() functions, and SCHED_RTPRIO, SCHED_NOAGE, and SCHED_OTHER in "Scheduling Policies" below.

If a process described by pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to pid.

If pid is zero, the scheduling parameters are set for the calling process.

If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function will affect the policy and priority of individual kernel schedulable entities in the process depending on their scheduling contention scope.

For threads created with system contention scope, this system call will have no effect on their scheduling or the scheduling of the underlying kernel scheduled entities.
For threads with process contention scope, the threads' scheduling parameters will not be affected. However, the underlying kernel scheduled entities for the process contention scope threads will have their scheduling parameters changed to the value specified in param. Kernel scheduled entities for use by process contention scope threads that are created after this call completes, inherit their scheduling policy and associated scheduling parameters from the process.
For single threaded processes, the scheduling parameters of its thread are also changed.

The priority returned is the old priority of the target process, though individual threads or lightweight processes may have a different value if some other interface is used to change an individual thread or lightweight processes priority.

Only a user with the OWNER privilege may change the scheduling parameters of another process.

The calling process must have the RTSCHED privilege to successfully call sched_setparam().

The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run.

If the priority of any kernel schedulable entities (threads) in the process is changed and is set higher than that of the lowest priority running thread, and if any of the modified threads is ready to run, then it will preempt the lower-priority running thread. Similarly, if the process calling sched_setparam() sets its own priority lower than that of one or more other nonempty thread lists, then the thread that is the head of the highest priority list will also preempt the calling thread. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority thread has executed.

sched_getparam()

The sched_getparam() function returns the scheduling parameters of a process specified by pid in the sched_param structure pointed to by param.

If a process described by pid exists, the scheduling parameters are returned for the process whose process ID is equal to pid.

If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function shall only return the process scheduling policy and priority. Individual threads or lightweight processes in the target process will have their own scheduling policies and priorities which may be different from the scheduling policy and priority of their process.

If pid is zero, the scheduling parameters are returned for the calling process.

sched_setscheduler()

The sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by pid to policy and the parameters specified in the sched_param structure pointed to by param, respectively. The value of the sched_priority member in the param structure can be any integer within the inclusive priority range for the scheduling policy specified by policy.

The possible values for the policy parameter are defined in the header file <sched.h>, and mentioned below.

If a process described by pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to pid.

If pid is zero, the scheduling policy and scheduling parameters are set for the calling process.

For threads created with system contention scope, this system call will have no effect on their scheduling or the scheduling of the underlying kernel scheduled entities.
For threads with process contention scope, the threads' scheduling parameters will not be affected. However, the underlying kernel scheduled entities for the process contention scope threads will have their scheduling parameters changed to the value specified in param. Kernel scheduled entities for use by process contention scope threads that are created after this call completes, inherit their scheduling policy and associated scheduling parameters from the process.

The priority returned is the old priority of the target process, though an individual thread or lightweight process may have a different value if some other interface is used to change individual thread's or lightweight process's priority.

The OWNER privilege is required to change the scheduling parameters of another process.

The calling process must have the RTSCHED privilege to successfully call sched_setscheduler().

The sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by pid to the values specified by policy and the structure param, respectively.

sched_getscheduler()

The sched_getscheduler() function returns the scheduling policy of the process specified by pid.

The values that can be returned by sched_getscheduler() are defined in the header file <sched.h> (see sched_setscheduler()).

If a process described by pid exists, the scheduling policy is returned for the process whose process ID is equal to pid.

If pid is zero, the scheduling policy is returned for the calling process.

sched_yield()

The sched_yield() function forces the calling thread to relinquish the processor until it again becomes the head of its thread list. It takes no arguments.

sched_get_priority_max()

sched_get_priority_min()

The sched_get_priority_max() and sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by policy.

The value of policy must be one of the scheduling policy values defined in <sched.h>.

sched_rr_get_interval()

The sched_rr_get_interval() function updates the timespec structure referenced by the interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by pid under the SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If pid is zero, the current execution time limit for the calling process is returned.

PRI_HPUX_TO_POSIX() and PRI_POSIX_TO_HPUX()

These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses smaller numbers for stronger priorities.

The PRI_HPUX_TO_POSIX() function returns the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument pri. The value of pri can be any integer.

The PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the priority passed in the argument pri. The value of pri can be any integer. The HP-UX priority returned is comparable to the values returned by getpriority() (see getpriority(2)).

Scheduling Policies

The scheduling policies described are defined in terms of a conceptual model, which contains a set of thread lists. There is, conceptually, one thread list for each priority. Any runnable thread may be in any thread list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving threads between and within lists).

Each thread will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the sched_setscheduler() or sched_setparam() functions. (However, these functions change scheduling parameters at process level for multithreaded processes).

Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies.

When a thread is to be selected to run, the thread that is at the head of the highest priority nonempty thread list is chosen. It is then removed from its thread list.

The following scheduling policies are defined:

SCHED_FIFO

First in-first out (FIFO) scheduling policy.

Threads scheduled under this policy are chosen from a thread list that is ordered by the time its threads have been in the list without being executed. Generally, the head of the list is the thread that has been in the list the longest time, and the tail is the thread that has been in the list the shortest time.

Under the SCHED_FIFO policy, the modification of the definitional thread lists is as follows:

When a running thread becomes a preempted thread, it becomes the head of the thread list for its priority.
When a blocked thread becomes a runnable thread, it becomes the tail of the thread list for its priority.
When a running thread calls the sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the param argument. If the thread of a process whose policy and priority have been modified is running or is runnable, it then becomes the tail of the thread list for its new priority.
When a running thread calls the sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the param argument. If the thread of a process whose priority has been modified is running or is runnable, it then becomes the tail of the thread list for its new priority.
When a running thread issues the sched_yield() function, the thread becomes the tail of the thread list for its priority.
At no other time is the position of a thread with this scheduling policy within the thread lists affected.

For this policy, valid priorities are within the range returned by the functions sched_get_priority_max() and sched_get_priority_min() when SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities.

SCHED_RR

Round-robin scheduling policy, with a per-system time slice (time quantum).

This policy is identical to the SCHED_FIFO policy with the additional condition that when the implementation detects that a running thread has been executing as a running thread for a time period of length returned by the function sched_rr_get_interval(), or longer, the thread becomes the tail of its thread list, and the head of that thread list is removed and made a running thread.

The effect of this policy is to ensure that if there are multiple SCHED_RR threads at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of SCHED_RR to ensure application progress among multiple processes if the application includes processes using the SCHED_FIFO policy at the same or higher priority levels, or SCHED_RR processes at a higher priority level.

A thread under this policy that is preempted and subsequently resumes execution as a running thread completes the unexpired portion of its round-robin interval time period.

For this policy, valid priorities are within the range returned by the functions sched_get_priority_max() and sched_get_priority_min() when SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities.

SCHED_RR2

Round-robin scheduling policy, with a per-priority time slice (time quantum).

This policy is identical to the SCHED_RR policy, except that the round-robin time slice interval returned by sched_rr_get_interval() depends upon the priority of the specified process.

SCHED_RTPRIO

Real-time scheduling policy with nondecaying priorities (like SCHED_FIFO and SCHED_RR) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see rtprio(2)).

For processes executing under this policy, the implementation must use only priorities within the range returned by the functions sched_get_priority_max() and sched_get_priority_min() when SCHED_RTPRIO is provided as the parameter. Note that, for the SCHED_RTPRIO scheduling policy, smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, SCHED_FIFO, SCHED_RR, and SCHED_RR2.

SCHED_OTHER (SCHED_HPUX, SCHED_TIMESHARE)

Another scheduling policy.

The SCHED_OTHER policy, also known as SCHED_HPUX and SCHED_TIMESHARE, provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy.

For processes executing under this policy, the implementation can use only priorities within the range returned by the functions sched_get_priority_max() and sched_get_priority_min() when SCHED_OTHER is provided as the parameter. Note that for the SCHED_OTHER scheduling policy, like SCHED_RTPRIO, smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the real-time scheduling policies described and the strongest priority in the priority range for SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, SCHED_FIFO, SCHED_RR, and SCHED_RR2.

SCHED_NOAGE

A timeshare scheduling policy with nondecaying priorities.

For processes executing under this policy, the implementation can use only priorities within the range returned by the functions sched_get_priority_max() and sched_get_priority_min() when SCHED_NOAGE is provided as the parameter. The priority range for the SCHED_NOAGE policy is a subset of the priority range supported by the SCHED_TIMESHARE policy. Note that for the SCHED_NOAGE scheduling policy, smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies.

The priority value of a thread executing with the SCHED_NOAGE policy is not decayed or boosted by the operating system scheduler. For SCHED_TIMESHARE policy, the priority value of the thread is decayed as the thread consumes processor cycles and boosted when the thread waits for processor cycles.

The threads in different processor sets do not compete with one another for processors based on their scheduling policy and priority values. The scheduler looks only at threads assigned to a processor's processor set to choose the next thread to run. A process with lower scheduling priority in one processor set may be executing while another process in another processor set with higher scheduling priority is waiting for the processor resources. This is applicable for all scheduling policies.

Security Restrictions

Some or all of the actions associated with this system call are subject to compartmental restrictions. See compartments(5) for more information about compartmentalization on systems that support that feature. Compartmental restrictions can be overridden if the process possesses the COMMALLOWED privilege (PRIV_COMMALLOWED). Processes owned by the superuser may not have this privilege. Processes owned by any user may have this privilege, depending on system configuration.

Some or all of the actions associated with this system call require the OWNER or the RTSCHED privilege. Processes owned by the superuser have these privileges. Processes owned by other users may have these privileges, depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

The functions return the following values:

sched_getparam()

sched_rr_get_interval()

sched_setparam()

sched_yield()

0: Successful completion.
-1: Failure. errno is set to indicate the error.

sched_setscheduler()

n: Successful completion. n is the former scheduling policy of the specified process.
-1: Failure. The policy and scheduling parameters remain unchanged. errno is set to indicate the error.

sched_getscheduler()

n: Successful completion. n is the scheduling policy of the specified process.
-1: Failure. errno is set to indicate the error.

sched_get_priority_max()

sched_get_priority_min()

n: Successful completion. n is the maximum or minimum value, respectively.
-1: Failure. errno is set to indicate the error.

PRI_HPUX_TO_POSIX()

n: Successful completion. n is the the POSIX.4 priority corresponding to pri.

PRI_POSIX_TO_HPUX()

n: Successful completion. n is the the HP-UX priority corresponding to pri.

ERRORS

If the functions fail, errno is set to one of the following values.

sched_setparam()

EFAULT: The param argument points to an invalid address.
EINVAL: One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified pid.
ENOSYS: The function is not supported by this implementation.
EPERM: The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the RTSCHED privilege to invoke sched_setparam().
ESRCH: No process can be found corresponding to that specified by pid.

sched_getparam()

EFAULT: The param argument points to an invalid address.
ENOSYS: The function is not supported by this implementation.
ESRCH: No process can be found corresponding to that specified by pid.

sched_setscheduler()

EFAULT: The param argument points to an invalid address.
EINVAL: The value of the policy parameter is invalid, or one or more of the parameters contained in param is outside the valid range for the specified scheduling policy.
ENOSYS: The function is not supported by this implementation.
EPERM: The requesting process does not have permission to set the scheduling policy of the specified process.
ESRCH: No process can be found corresponding to that specified by pid.

sched_getscheduler()

ENOSYS: The function is not supported by this implementation.
ESRCH: No process can be found corresponding to that specified by pid.

sched_yield()

ENOSYS: The function is not supported by this implementation.

sched_get_priority_max()

sched_get_priority_min()

EINVAL: The value of the policy parameter does not represent a defined scheduling policy.
ENOSYS: The function is not supported by this implementation.

sched_rr_get_interval()

ENOSYS: The function is not supported by this implementation.
ESRCH: No process can be found corresponding to that specified by pid.

EXAMPLES

Change the calling process to use the strongest FIFO priority:

#include <sched.h> 

struct sched_param param; 
int maxpri; 

maxpri = sched_get_priority_max(SCHED_FIFO); 
if (maxpri == -1) { 
    perror("sched_get_priority_max() failed"); 
    exit(1); 
} 
param.sched_priority = maxpri; 
if (sched_setscheduler(getpid(), SCHED_FIFO, &param) == -1) { 
    perror("sched_setscheduler() failed"); 
    exit(1); 
} 

AUTHOR

The sched_*() functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14.

PRI_HPUX_TO_POSIX() and PRI_POSIX_TO_HPUX() were developed by HP.

STANDARDS CONFORMANCE

sched_get_priority_max(): POSIX.4

sched_get_priority_min(): POSIX.4

sched_getparam(): POSIX.4

sched_getscheduler(): POSIX.4

sched_rr_getinterval(): POSIX.4

sched_setparam(): POSIX.4

sched_setscheduler(): POSIX.4

sched_yield(): POSIX.4