Modified to document new SCHED_BATCH policy, new in kernel 2.6.16.

Text describing SCHED_BATCH was added to sched_setscheduler.2, and was drawn in part from Ingo Molnar's description in the message containing the patch that implemented this policy. Various other minor rewordings and formatting fixes.
author: Michael Kerrisk <mtk.manpages@gmail.com> 2006-03-23 01:06:07 +0000
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2006-03-23 01:06:07 +0000
commit: 92c37d8cb0a3be60bc3f682cc91c8a635f70b6da (patch)
tree: 5800a2dc8b8da4c8a9ba4249c211938cb14dd931
parent: 651946d5d78d17176e79a159700d95e4954e0ce5 (diff)
download: man-pages-92c37d8cb0a3be60bc3f682cc91c8a635f70b6da.tar.gz
3 files changed, 75 insertions, 67 deletions
diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2
index 8d32f20f36..953ee2c8c9 100644
--- a/man2/sched_get_priority_max.2
+++ b/man2/sched_get_priority_max.2
@@ -27,7 +27,7 @@
 .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
 .\"            revision
 .\"
-.TH GET_PRIORITY_MAX 2 1996-04-10 "Linux 1.3.81" "Linux Programmer's Manual"
+.TH GET_PRIORITY_MAX 2 2006-03-23 "Linux 2.6.16" "Linux Programmer's Manual"
 .SH NAME
 sched_get_priority_max, sched_get_priority_min  \- get static priority range
 .SH SYNOPSIS
@@ -47,9 +47,11 @@ scheduling algorithm identified by \fIpolicy\fR. Supported \fIpolicy\fR
 values are
 .IR SCHED_FIFO , 
 .IR SCHED_RR ,
+.IR SCHED_OTHER ,
 and 
-.IR SCHED_OTHER .
-.\" FIXME 2.6.16-rc6 has SCHED_BATCH; this must be documented.
+.IR SCHED_BATCH .
+Further details about these policies can be found in
+.BR sched_setscheduler (2).
 
 Processes with numerically higher priority values are scheduled before
 processes with numerically lower priority values. Thus, the value
@@ -58,7 +60,8 @@ value returned by \fBsched_get_priority_min\fR().
 
 Linux allows the static priority value range 1 to 99 for
 \fISCHED_FIFO\fR and \fISCHED_RR\fR and the priority 0 for
-\fISCHED_OTHER\fR. Scheduling priority ranges for the various policies
+\fISCHED_OTHER\fR and \fISCHED_BATCH\fP. 
+Scheduling priority ranges for the various policies
 are not alterable.
 
 The range of scheduling priorities may vary on other POSIX systems,
@@ -75,7 +78,6 @@ and
 are available define
 .I _POSIX_PRIORITY_SCHEDULING
 in <unistd.h>.
-
 .SH "RETURN VALUE"
 On success,
 .BR sched_get_priority_max ()
@@ -83,7 +85,7 @@ and
 .BR sched_get_priority_min ()
 return the maximum/minimum priority value for the named scheduling
 policy.
-On error, \-1 is returned,
+On error, \-1 is returned, and
 .I errno
 is set appropriately.
 .SH ERRORS
@@ -100,9 +102,6 @@ POSIX.1b (formerly POSIX.4)
 .BR sched_setparam (2),
 .BR sched_setscheduler (2)
 .PP
-.BR sched_setscheduler (2)
-has a description of the Linux scheduling scheme.
-.PP
 .I Programming for the real world \- POSIX.4
 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0
 .br
diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2
index ee11453ada..60f4880e0e 100644
--- a/man2/sched_setparam.2
+++ b/man2/sched_setparam.2
@@ -28,37 +28,34 @@
 .\"            revision
 .\" Modified 2004-05-27 by Michael Kerrisk <mtk-manpages@gmx.net>
 .\"
-.TH SCHED_SETPARAM 2 2005-07-28 "Linux 2.6.12" "Linux Programmer's Manual"
+.TH SCHED_SETPARAM 2 2006-03-23 "Linux 2.6.16" "Linux Programmer's Manual"
 .SH NAME
 sched_setparam, sched_getparam \- set and get scheduling parameters
 .SH SYNOPSIS
+.nf
 .B #include <sched.h>
 .sp
-\fBint sched_setparam(pid_t \fIpid\fB, const struct sched_param *\fIp\fB);
+\fBint sched_setparam(pid_t \fIpid\fB, const struct sched_param *\fIparam\fB);
 .sp
-\fBint sched_getparam(pid_t \fIpid\fB, struct sched_param *\fIp\fB);
+\fBint sched_getparam(pid_t \fIpid\fB, struct sched_param *\fIparam\fB);
 .sp
-.nf
-.ta 4n
 \fBstruct sched_param {
-	...
-	int \fIsched_priority\fB;
-	...
+    ...
+    int \fIsched_priority\fB;
+    ...
 };
-.ta
 .fi
 .SH DESCRIPTION
 .BR sched_setparam ()
 sets the scheduling parameters associated with the scheduling policy
 for the process identified by \fIpid\fR. If \fIpid\fR is zero, then
 the parameters of the current process are set. The interpretation of
-the parameter \fIp\fR depends on the selected policy. Currently, the
-following three scheduling policies are supported under Linux:
-.IR SCHED_FIFO , 
-.IR SCHED_RR ,
-and 
-.IR SCHED_OTHER .
-.\" FIXME 2.6.16-rc6 has SCHED_BATCH; this must be documented.
+the parameter \fIparam\fR depends on the scheduling 
+policy of the process identified by
+.IR pid . 
+See 
+.BR sched_setscheduler (2)
+for a description of the scheduling policies supported under Linux.
 
 .BR sched_getparam ()
 retrieves the scheduling parameters for the 
@@ -66,10 +63,10 @@ process identified by \fIpid\fR. If \fIpid\fR is zero, then the parameters
 of the current process are retrieved. 
 
 .BR sched_setparam ()
-checks the validity of \fIp\fR for the scheduling policy of the
-process. The parameter \fIp->sched_priority\fR must lie within the
-range given by \fBsched_get_priority_min\fR and
-\fBsched_get_priority_max\fR.
+checks the validity of \fIparam\fR for the scheduling policy of the
+process. The parameter \fIparam->sched_priority\fR must lie within the
+range given by \fBsched_get_priority_min\fR(2) and
+\fBsched_get_priority_max\fR(2).
 
 For a discussion of the privileges and resource limits related to 
 scheduling priority and policy, see
@@ -82,20 +79,19 @@ and
 are available define
 .I _POSIX_PRIORITY_SCHEDULING
 in <unistd.h>.
-
 .SH "RETURN VALUE"
 On success,
 .BR sched_setparam ()
 and
 .BR sched_getparam ()
 return 0.
-On error, \-1 is returned,
+On error, \-1 is returned, and
 .I errno
 is set appropriately.
 .SH ERRORS
 .TP
 .B EINVAL
-The parameter \fIp\fR does not make sense for the current
+The parameter \fIparam\fR does not make sense for the current
 scheduling policy.
 .TP
 .B EPERM
@@ -120,9 +116,6 @@ POSIX.1b (formerly POSIX.4)
 .BR setpriority (2),
 .BR capabilities (7)
 .PP
-.BR sched_setscheduler (2)
-has a description of the Linux scheduling scheme.
-.PP
 .I Programming for the real world \- POSIX.4
 by Bill O. Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0
 .br
diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2
index ced3e6436d..2ed1c603db 100644
--- a/man2/sched_setscheduler.2
+++ b/man2/sched_setscheduler.2
@@ -32,47 +32,48 @@
 .\"		sched_setscheduler()
 .\"	A couple of grammar clean-ups
 .\" Modified 2004-05-27 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\" 2005-03-23, mtk, Added description of SCHED_BATCH.
 .\"
-.TH SETSCHEDULER 2 2005-07-28 "Linux 2.6.12" "Linux Programmer's Manual"
+.TH SETSCHEDULER 2 2006-03-23 "Linux 2.6.16" "Linux Programmer's Manual"
 .SH NAME
 sched_setscheduler, sched_getscheduler \-
 set and get scheduling algorithm/parameters
 .SH SYNOPSIS
+.nf
 .B #include <sched.h>
 .sp
 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
-.BI "const struct sched_param *" p );
+.br
+.BI "                       const struct sched_param *" param );
 .sp
 .BI "int sched_getscheduler(pid_t " pid );
 .sp
-.nf
-.ta 4n
 \fBstruct sched_param {
-	...
-	int \fIsched_priority\fB;
-	...
+    ...
+    int \fIsched_priority\fB;
+    ...
 };
-.ta
 .fi
 .SH DESCRIPTION
 .BR sched_setscheduler ()
 sets both the scheduling policy and the associated parameters for the
 process identified by \fIpid\fP. If \fIpid\fP equals zero, the
 scheduler of the calling process will be set. The interpretation of
-the parameter \fIp\fP depends on the selected policy. Currently, the
+the parameter \fIparam\fP depends on the selected policy. Currently, the
 following three scheduling policies are supported under Linux:
 .IR SCHED_FIFO , 
 .IR SCHED_RR ,
-and 
-.IR SCHED_OTHER ;
+.IR SCHED_OTHER ,
+.\" In the 2.6 kernel sources, SCHED_OTHER is actually called 
+.\" SCHED_NORMAL.
+and
+.IR SCHED_BATCH ;
 their respective semantics are described below.
 
 .BR sched_getscheduler ()
 queries the scheduling policy currently applied to the process
 identified by \fIpid\fP. If \fIpid\fP equals zero, the policy of the
 calling process will be retrieved.
-
-
 .SS Scheduling Policies
 The scheduler is the kernel part that decides which runnable process
 will be executed by the CPU next. The Linux scheduler offers three
@@ -89,11 +90,16 @@ each process, where it will be inserted into the list of processes
 with equal static priority and how it will move inside this list.
 
 \fISCHED_OTHER\fP is the default universal time-sharing scheduler
-policy used by most processes, \fISCHED_FIFO\fP and \fISCHED_RR\fP are
+policy used by most processes.
+\fISCHED_BATCH\fP is intended for "batch" style execution of processes.
+\fISCHED_FIFO\fP and \fISCHED_RR\fP are
 intended for special time-critical applications that need precise
 control over the way in which runnable processes are selected for
-execution. Processes scheduled with \fISCHED_OTHER\fP must be assigned
-the static priority 0, processes scheduled under \fISCHED_FIFO\fP or
+execution. 
+
+Processes scheduled with \fISCHED_OTHER\fP or \fISCHED_BATCH\fP
+must be assigned the static priority 0.
+Processes scheduled under \fISCHED_FIFO\fP or
 \fISCHED_RR\fP can have a static priority in the range 1 to 99. 
 The system calls \fBsched_get_priority_min\fP() and
 \fBsched_get_priority_max\fP() can be used to find out the valid
@@ -105,12 +111,12 @@ priority gets ready to run, the current process will be preempted and
 returned into its wait list. The scheduling policy only determines the
 ordering within the list of runnable processes with equal static
 priority.
-
 .SS SCHED_FIFO: First In-First Out scheduling
 \fISCHED_FIFO\fP can only be used with static priorities higher than
 0, which means that when a \fISCHED_FIFO\fP processes becomes runnable,
-it will always preempt immediately any currently running normal
-\fISCHED_OTHER\fP process. \fISCHED_FIFO\fP is a simple scheduling
+it will always immediately preempt any currently running
+\fISCHED_OTHER\fP or \fISCHED_BATCH\fP process. 
+\fISCHED_FIFO\fP is a simple scheduling
 algorithm without time slicing. For processes scheduled under the
 \fISCHED_FIFO\fP policy, the following rules are applied: A
 \fISCHED_FIFO\fP process that has been preempted by another process of
@@ -133,7 +139,6 @@ scheduled under the \fISCHED_FIFO\fP policy in the wait list of
 runnable processes with equal static priority. A \fISCHED_FIFO\fP
 process runs until either it is blocked by an I/O request, it is
 preempted by a higher priority process, or it calls \fBsched_yield\fP().
-
 .SS SCHED_RR: Round Robin scheduling
 \fISCHED_RR\fP is a simple enhancement of \fISCHED_FIFO\fP. Everything
 described above for \fISCHED_FIFO\fP also applies to \fISCHED_RR\fP,
@@ -144,12 +149,10 @@ end of the list for its priority. A \fISCHED_RR\fP process that has
 been preempted by a higher priority process and subsequently resumes
 execution as a running process will complete the unexpired portion of
 its round robin time quantum. The length of the time quantum can be
-retrieved by \fBsched_rr_get_interval\fP().
+retrieved using \fBsched_rr_get_interval\fP(2).
 .\" On Linux 2.4, the length of the RR interval is influenced
 .\" by the process nice value -- MTK
 .\"
-.\" FIXME 2.6.16-rc6 has SCHED_BATCH; this must be documented.
-
 .SS SCHED_OTHER: Default Linux time-sharing scheduling
 \fISCHED_OTHER\fP can only be used at static priority 0.
 \fISCHED_OTHER\fP is the standard Linux time-sharing scheduler that is
@@ -157,11 +160,26 @@ intended for all processes that do not require special static priority
 real-time mechanisms. The process to run is chosen from the static
 priority 0 list based on a dynamic priority that is determined only
 inside this list. The dynamic priority is based on the nice level (set
-by the \fBnice\fP() or \fBsetpriority\fP() system call) and increased for
+by \fBnice\fP(2) or \fBsetpriority\fP(2)) and increased for
 each time quantum the process is ready to run, but denied to run by
 the scheduler. This ensures fair progress among all \fISCHED_OTHER\fP
 processes.
-
+.SS SCHED_BATCH: Scheduling batch processes
+(Since Linux 2.6.16.)
+\fISCHED_BATCH\fP can only be used at static priority 0.
+This policy is similar to \fISCHED_OTHER\fP, except that
+this policy will cause the scheduler to always assume
+that the process is CPU-intensive.
+Consequently, the scheduler will apply a small scheduling
+penalty so that this process is mildy disfavoured in scheduling
+decisions.
+.\" The following paragraph is drawn largely from the text that 
+.\" accompanied Ingo Molnar's patch for the implementation of 
+.\" SCHED_BATCH.
+This policy is useful for workloads that are non-interactive,
+but do not want to lower their nice value, 
+and for workloads that want a deterministic scheduling policy without 
+interactivity causing extra preemptions (between the workload's tasks).
 .SS Privileges and resource limits
 .\" FIXME -- make some general statement about Unix implementations
 .\" A process calling 
@@ -215,7 +233,6 @@ Privileged
 .RB ( CAP_SYS_NICE )
 processes ignore this limit; as with older older kernels,
 they can make arbitrary changes to scheduling policy and priority.
-
 .SS Response time
 A blocked high priority process waiting for the I/O has a certain
 response time before it is scheduled again. The device driver writer
@@ -223,7 +240,6 @@ can greatly reduce this response time by using a "slow interrupt"
 interrupt handler.
 .\" as described in
 .\" .BR request_irq (9).
-
 .SS Miscellaneous
 Child processes inherit the scheduling algorithm and parameters across a
 .BR fork ().
@@ -248,7 +264,6 @@ and
 are available define
 .I _POSIX_PRIORITY_SCHEDULING
 in <unistd.h>.
-
 .SH "RETURN VALUE"
 On success,
 .BR sched_setscheduler ()
@@ -256,14 +271,14 @@ returns zero.
 On success,
 .BR sched_getscheduler ()
 returns the policy for the process (a non-negative integer).  
-On error, \-1 is returned,
+On error, \-1 is returned, and
 .I errno
 is set appropriately.
 .SH ERRORS
 .TP
 .B EINVAL
 The scheduling \fIpolicy\fP is not one of the recognized policies,
-or the parameter \fIp\fP does not make sense for the \fIpolicy\fP.
+or the parameter \fIparam\fP does not make sense for the \fIpolicy\fP.
 .TP
 .B EPERM
 The calling process does not have appropriate privileges.
@@ -271,8 +286,9 @@ The calling process does not have appropriate privileges.
 .B ESRCH
 The process whose ID is \fIpid\fP could not be found.
 .SH "CONFORMING TO"
-POSIX.1b (formerly POSIX.4)
-.SH NOTE
+POSIX.1b (formerly POSIX.4).
+The \fISCHED_BATCH\fP policy is Linux specific.
+.SH NOTES
 Standard Linux is a general-purpose operating system
 and can handle background processes,
 interactive applications, and soft real-time applications
author	Michael Kerrisk <mtk.manpages@gmail.com>	2006-03-23 01:06:07 +0000
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2006-03-23 01:06:07 +0000
commit	92c37d8cb0a3be60bc3f682cc91c8a635f70b6da (patch)
tree	5800a2dc8b8da4c8a9ba4249c211938cb14dd931
parent	651946d5d78d17176e79a159700d95e4954e0ce5 (diff)
download	man-pages-92c37d8cb0a3be60bc3f682cc91c8a635f70b6da.tar.gz