| Message ID | 87sgz9fq53.fsf@oldenburg2.str.redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | manual: Document lack of conformance of sched_* functions [BZ #14829] | expand |
On 12/7/18 8:00 AM, Florian Weimer wrote: > On Linux, we define _POSIX_PRIORITY_SCHEDULING, but functions such > as sched_setparam and sched_setscheduler apply to individual threads, > not processes. I agree. This has always been a long-standing issue that has bothered me. Please accept my gracious thanks for fixing this. I wish we could do more, but we are limited by the underlying OS and how the that maps into POSIX. I'd like to see a v2 of this, and I'll review the text again. Thanks. > 2018-12-07 Florian Weimer <fweimer@redhat.com> > > [BZ #14829] > * manual/resource.texi (Basic Scheduling Functions): Add > portability note. Change process to task throughout the section. > Remove incorrect comment about sched_yield as it affects > tasks/threads, not entire processes. I think we need a *big* comment in sysdeps/unix/sysv/linux/bits/posix_opt.h around the define of _POSIX_PRIORITY_SCHEDULING which says: /* On Linux we do not conform to the POSIX requirements for setting _POSIX_PRIORITY_SCHEDULING, and it should be set to -1, but it has been enabled for so long that we cannot risk setting it to -1 without serious issues arising with existing applications, so we leave it enabled even though on Linux the APIs all take thread IDs. Please see bug 14829. */ What do you think? > diff --git a/manual/resource.texi b/manual/resource.texi > index 8bc2a803d4..f02192475a 100644 > --- a/manual/resource.texi > +++ b/manual/resource.texi > @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. > > The symbols in this section are declared by including file @file{sched.h}. > > +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the > +functions below refer to process IDs. On Linux, they are actually > +thread IDs, and control how specific threads are scheduled with > +regards to the entire system. The resulting behavior does not conform > +to POSIX. This is why the following description refers to tasks and > +tasks IDs, and not processes and process IDs. > +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 OK. Should we also mention that PTHREAD_SCOPE_PROCESS is entirely unsupported by glibc on Linux? > + > @deftp {Data Type} {struct sched_param} > @standards{POSIX, sched.h} > This structure describes an absolute priority. > @@ -765,11 +773,11 @@ absolute priority value > @c Direct syscall, Linux only. > > This function sets both the absolute priority and the scheduling policy > -for a process. > +for a task. OK. > > It assigns the absolute priority value given by @var{param} and the > -scheduling policy @var{policy} to the process with Process ID @var{pid}, > -or the calling process if @var{pid} is zero. If @var{policy} is > +scheduling policy @var{policy} to the task with ID @var{pid}, > +or the calling task if @var{pid} is zero. If @var{policy} is OK. > negative, @code{sched_setscheduler} keeps the existing scheduling policy. > > The following macros represent the valid values for @var{policy}: > @@ -795,20 +803,20 @@ to this function are: > @item EPERM > @itemize @bullet > @item > -The calling process does not have @code{CAP_SYS_NICE} permission and > +The calling task does not have @code{CAP_SYS_NICE} permission and OK. > @var{policy} is not @code{SCHED_OTHER} (or it's negative and the > existing policy is not @code{SCHED_OTHER}. > > @item > -The calling process does not have @code{CAP_SYS_NICE} permission and its > -owner is not the target process' owner. I.e., the effective uid of the > -calling process is neither the effective nor the real uid of process > +The calling task does not have @code{CAP_SYS_NICE} permission and its > +owner is not the target task's owner. I.e., the effective uid of the > +calling task is neither the effective nor the real uid of task OK. > @var{pid}. > @c We need a cross reference to the capabilities section, when written. > @end itemize > > @item ESRCH > -There is no process with pid @var{pid} and @var{pid} is not zero. > +There is no task with pid @var{pid} and @var{pid} is not zero. OK. > > @item EINVAL > @itemize @bullet > @@ -835,8 +843,8 @@ tell you what the valid range is. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function returns the scheduling policy assigned to the process with > -Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. > +This function returns the scheduling policy assigned to the task with > +ID @var{pid}, or the calling task if @var{pid} is zero. OK. > > The return value is the scheduling policy. See > @code{sched_setscheduler} for the possible values. > @@ -849,7 +857,7 @@ The @code{errno} values specific to this function are: > @table @code > > @item ESRCH > -There is no process with pid @var{pid} and it is not zero. > +There is no task with pid @var{pid} and it is not zero. OK. > > @item EINVAL > @var{pid} is negative. > @@ -869,7 +877,7 @@ absolute priority, use @code{sched_getparam}. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function sets a process' absolute priority. > +This function sets a task's absolute priority. OK. > > It is functionally identical to @code{sched_setscheduler} with > @var{policy} = @code{-1}. > @@ -883,13 +891,13 @@ It is functionally identical to @code{sched_setscheduler} with > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function returns a process' absolute priority. > +This function returns a task's absolute priority. OK. > > -@var{pid} is the Process ID (pid) of the process whose absolute priority > -you want to know. > +@var{pid} is the task ID of the task whose absolute priority you want > +to know. Ok. > > @var{param} is a pointer to a structure in which the function stores the > -absolute priority of the process. > +absolute priority of the task. OK. > > On success, the return value is @code{0}. Otherwise, it is @code{-1} > and @code{errno} is set accordingly. The @code{errno} values specific > @@ -898,7 +906,7 @@ to this function are: > @table @code > > @item ESRCH > -There is no process with pid @var{pid} and it is not zero. > +There is no task with ID @var{pid} and it is not zero. OK. > > @item EINVAL > @var{pid} is negative. > @@ -914,7 +922,7 @@ There is no process with pid @var{pid} and it is not zero. > @c Direct syscall, Linux only. > > This function returns the lowest absolute priority value that is > -allowable for a process with scheduling policy @var{policy}. > +allowable for a task with scheduling policy @var{policy}. OK. > > On Linux, it is 0 for SCHED_OTHER and 1 for everything else. > > @@ -935,7 +943,7 @@ to this function are: > @c Direct syscall, Linux only. > > This function returns the highest absolute priority value that is > -allowable for a process that with scheduling policy @var{policy}. > +allowable for a task that with scheduling policy @var{policy}. OK. > > On Linux, it is 0 for SCHED_OTHER and 99 for everything else. > > @@ -956,8 +964,8 @@ to this function are: > @c Direct syscall, Linux only. > > This function returns the length of the quantum (time slice) used with > -the Round Robin scheduling policy, if it is used, for the process with > -Process ID @var{pid}. > +the Round Robin scheduling policy, if it is used, for the task with > +task ID @var{pid}. OK. > > It returns the length of time as @var{interval}. > @c We need a cross-reference to where timespec is explained. But that > @@ -980,18 +988,18 @@ function, so there are no specific @code{errno} values. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall on Linux; alias to swtch on HURD. > > -This function voluntarily gives up the process' claim on the CPU. > +This function voluntarily gives up the task's claim on the CPU. OK. > > -Technically, @code{sched_yield} causes the calling process to be made > +Technically, @code{sched_yield} causes the calling task to be made OK. > immediately ready to run (as opposed to running, which is what it was > before). This means that if it has absolute priority higher than 0, it > -gets pushed onto the tail of the queue of processes that share its > +gets pushed onto the tail of the queue of tasks that share its OK. > absolute priority and are ready to run, and it will run again when its > turn next arrives. If its absolute priority is 0, it is more > complicated, but still has the effect of yielding the CPU to other > -processes. > +tasks. OK. > > -If there are no other processes that share the calling process' absolute > +If there are no other tasks that share the calling task's absolute > priority, this function doesn't have any effect. OK. > > To the extent that the containing program is oblivious to what other >
* Carlos O'Donell: >> 2018-12-07 Florian Weimer <fweimer@redhat.com> >> >> [BZ #14829] >> * manual/resource.texi (Basic Scheduling Functions): Add >> portability note. Change process to task throughout the section. >> Remove incorrect comment about sched_yield as it affects >> tasks/threads, not entire processes. > > I think we need a *big* comment in sysdeps/unix/sysv/linux/bits/posix_opt.h > around the define of _POSIX_PRIORITY_SCHEDULING which says: > > /* On Linux we do not conform to the POSIX requirements for setting > _POSIX_PRIORITY_SCHEDULING, and it should be set to -1, but it has > been enabled for so long that we cannot risk setting it to -1 without > serious issues arising with existing applications, so we leave it enabled > even though on Linux the APIs all take thread IDs. Please see bug 14829. */ > > What do you think? I think that is a separate discussion. We could stop defining _POSIX_PRIORITY_SCHEDULING to -1, but still provide the corresponding definitions and declarations under _GNU_SOURCE. Whether that's feasible requires substantial additional research. I'm fine with adding a comment to sysdeps/unix/sysv/linux/bits/posix_opt.h along the lines you suggested, maybe: /* Priority scheduling is not supported with the correct semantics, but GNU/Linux applications expect that the corresponding interfaces are available, even though the semantics do not meet the POSIX requirements. */ #define _POSIX_PRIORITY_SCHEDULING 200809L Or we could use the text you proposed. >> diff --git a/manual/resource.texi b/manual/resource.texi >> index 8bc2a803d4..f02192475a 100644 >> --- a/manual/resource.texi >> +++ b/manual/resource.texi >> @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. >> >> The symbols in this section are declared by including file @file{sched.h}. >> >> +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the >> +functions below refer to process IDs. On Linux, they are actually >> +thread IDs, and control how specific threads are scheduled with >> +regards to the entire system. The resulting behavior does not conform >> +to POSIX. This is why the following description refers to tasks and >> +tasks IDs, and not processes and process IDs. >> +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 > > OK. > > Should we also mention that PTHREAD_SCOPE_PROCESS is entirely unsupported by > glibc on Linux? Wouldn't that be something for the documentation of pthread_attr_setscope, which does not exist yet? Thanks, Florian
On 12/14/18 4:08 PM, Florian Weimer wrote: > * Carlos O'Donell: > >>> 2018-12-07 Florian Weimer <fweimer@redhat.com> >>> >>> [BZ #14829] >>> * manual/resource.texi (Basic Scheduling Functions): Add >>> portability note. Change process to task throughout the section. >>> Remove incorrect comment about sched_yield as it affects >>> tasks/threads, not entire processes. >> >> I think we need a *big* comment in sysdeps/unix/sysv/linux/bits/posix_opt.h >> around the define of _POSIX_PRIORITY_SCHEDULING which says: >> >> /* On Linux we do not conform to the POSIX requirements for setting >> _POSIX_PRIORITY_SCHEDULING, and it should be set to -1, but it has >> been enabled for so long that we cannot risk setting it to -1 without >> serious issues arising with existing applications, so we leave it enabled >> even though on Linux the APIs all take thread IDs. Please see bug 14829. */ >> >> What do you think? > > I think that is a separate discussion. Yes, yes, absolutely, but if anyone goes looking in the header today it looks like rainbows, gumdrops, and candy canes. We should add a warning in a comment for anyone reading the source that this is busted. > We could stop defining _POSIX_PRIORITY_SCHEDULING to -1, but still > provide the corresponding definitions and declarations under > _GNU_SOURCE. Whether that's feasible requires substantial additional > research. Agreed. > I'm fine with adding a comment to > sysdeps/unix/sysv/linux/bits/posix_opt.h along the lines you suggested, > maybe: > > /* Priority scheduling is not supported with the correct semantics, but > GNU/Linux applications expect that the corresponding interfaces are > available, even though the semantics do not meet the POSIX > requirements. */ > #define _POSIX_PRIORITY_SCHEDULING 200809L This text is fine. My preference is to add a trailing "(See bug 14829)", since finding that bug helps readers see what's going on. > > Or we could use the text you proposed. > >>> diff --git a/manual/resource.texi b/manual/resource.texi >>> index 8bc2a803d4..f02192475a 100644 >>> --- a/manual/resource.texi >>> +++ b/manual/resource.texi >>> @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. >>> >>> The symbols in this section are declared by including file @file{sched.h}. >>> >>> +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the >>> +functions below refer to process IDs. On Linux, they are actually >>> +thread IDs, and control how specific threads are scheduled with >>> +regards to the entire system. The resulting behavior does not conform >>> +to POSIX. This is why the following description refers to tasks and >>> +tasks IDs, and not processes and process IDs. >>> +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 >> >> OK. >> >> Should we also mention that PTHREAD_SCOPE_PROCESS is entirely unsupported by >> glibc on Linux? > > Wouldn't that be something for the documentation of > pthread_attr_setscope, which does not exist yet? Oh, good point. OK, drop that suggestion.
* Carlos O'Donell: > My preference is to add a trailing "(See bug 14829)", since finding that > bug helps readers see what's going on. Sure. Please see the patch below. Thanks, Florian ----- On Linux, we define _POSIX_PRIORITY_SCHEDULING, but functions such as sched_setparam and sched_setscheduler apply to individual threads, not processes. 2018-12-14 Florian Weimer <fweimer@redhat.com> [BZ #14829] * manual/resource.texi (Basic Scheduling Functions): Add portability note. Change process to task throughout the section. Remove incorrect comment about sched_yield as it affects tasks/threads, not entire processes. * sysdeps/unix/sysv/linux/bits/posix_opt.h (_POSIX_PRIORITY_SCHEDULING): Update comment. diff --git a/manual/resource.texi b/manual/resource.texi index 8c4c92a184..60e6d61611 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. The symbols in this section are declared by including file @file{sched.h}. +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the +functions below refer to process IDs. On Linux, they are actually +thread IDs, and control how specific threads are scheduled with +regards to the entire system. The resulting behavior does not conform +to POSIX. This is why the following description refers to tasks and +tasks IDs, and not processes and process IDs. +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 + @deftp {Data Type} {struct sched_param} @standards{POSIX, sched.h} This structure describes an absolute priority. @@ -765,11 +773,11 @@ absolute priority value @c Direct syscall, Linux only. This function sets both the absolute priority and the scheduling policy -for a process. +for a task. It assigns the absolute priority value given by @var{param} and the -scheduling policy @var{policy} to the process with Process ID @var{pid}, -or the calling process if @var{pid} is zero. If @var{policy} is +scheduling policy @var{policy} to the task with ID @var{pid}, +or the calling task if @var{pid} is zero. If @var{policy} is negative, @code{sched_setscheduler} keeps the existing scheduling policy. The following macros represent the valid values for @var{policy}: @@ -795,20 +803,20 @@ to this function are: @item EPERM @itemize @bullet @item -The calling process does not have @code{CAP_SYS_NICE} permission and +The calling task does not have @code{CAP_SYS_NICE} permission and @var{policy} is not @code{SCHED_OTHER} (or it's negative and the existing policy is not @code{SCHED_OTHER}. @item -The calling process does not have @code{CAP_SYS_NICE} permission and its -owner is not the target process' owner. I.e., the effective uid of the -calling process is neither the effective nor the real uid of process +The calling task does not have @code{CAP_SYS_NICE} permission and its +owner is not the target task's owner. I.e., the effective uid of the +calling task is neither the effective nor the real uid of task @var{pid}. @c We need a cross reference to the capabilities section, when written. @end itemize @item ESRCH -There is no process with pid @var{pid} and @var{pid} is not zero. +There is no task with pid @var{pid} and @var{pid} is not zero. @item EINVAL @itemize @bullet @@ -835,8 +843,8 @@ tell you what the valid range is. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function returns the scheduling policy assigned to the process with -Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. +This function returns the scheduling policy assigned to the task with +ID @var{pid}, or the calling task if @var{pid} is zero. The return value is the scheduling policy. See @code{sched_setscheduler} for the possible values. @@ -849,7 +857,7 @@ The @code{errno} values specific to this function are: @table @code @item ESRCH -There is no process with pid @var{pid} and it is not zero. +There is no task with pid @var{pid} and it is not zero. @item EINVAL @var{pid} is negative. @@ -869,7 +877,7 @@ absolute priority, use @code{sched_getparam}. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function sets a process' absolute priority. +This function sets a task's absolute priority. It is functionally identical to @code{sched_setscheduler} with @var{policy} = @code{-1}. @@ -883,13 +891,13 @@ It is functionally identical to @code{sched_setscheduler} with @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function returns a process' absolute priority. +This function returns a task's absolute priority. -@var{pid} is the Process ID (pid) of the process whose absolute priority -you want to know. +@var{pid} is the task ID of the task whose absolute priority you want +to know. @var{param} is a pointer to a structure in which the function stores the -absolute priority of the process. +absolute priority of the task. On success, the return value is @code{0}. Otherwise, it is @code{-1} and @code{errno} is set accordingly. The @code{errno} values specific @@ -898,7 +906,7 @@ to this function are: @table @code @item ESRCH -There is no process with pid @var{pid} and it is not zero. +There is no task with ID @var{pid} and it is not zero. @item EINVAL @var{pid} is negative. @@ -914,7 +922,7 @@ There is no process with pid @var{pid} and it is not zero. @c Direct syscall, Linux only. This function returns the lowest absolute priority value that is -allowable for a process with scheduling policy @var{policy}. +allowable for a task with scheduling policy @var{policy}. On Linux, it is 0 for SCHED_OTHER and 1 for everything else. @@ -935,7 +943,7 @@ to this function are: @c Direct syscall, Linux only. This function returns the highest absolute priority value that is -allowable for a process that with scheduling policy @var{policy}. +allowable for a task that with scheduling policy @var{policy}. On Linux, it is 0 for SCHED_OTHER and 99 for everything else. @@ -956,8 +964,8 @@ to this function are: @c Direct syscall, Linux only. This function returns the length of the quantum (time slice) used with -the Round Robin scheduling policy, if it is used, for the process with -Process ID @var{pid}. +the Round Robin scheduling policy, if it is used, for the task with +task ID @var{pid}. It returns the length of time as @var{interval}. @c We need a cross-reference to where timespec is explained. But that @@ -980,18 +988,18 @@ function, so there are no specific @code{errno} values. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on Linux; alias to swtch on HURD. -This function voluntarily gives up the process' claim on the CPU. +This function voluntarily gives up the task's claim on the CPU. -Technically, @code{sched_yield} causes the calling process to be made +Technically, @code{sched_yield} causes the calling task to be made immediately ready to run (as opposed to running, which is what it was before). This means that if it has absolute priority higher than 0, it -gets pushed onto the tail of the queue of processes that share its +gets pushed onto the tail of the queue of tasks that share its absolute priority and are ready to run, and it will run again when its turn next arrives. If its absolute priority is 0, it is more complicated, but still has the effect of yielding the CPU to other -processes. +tasks. -If there are no other processes that share the calling process' absolute +If there are no other tasks that share the calling task's absolute priority, this function doesn't have any effect. To the extent that the containing program is oblivious to what other diff --git a/sysdeps/unix/sysv/linux/bits/posix_opt.h b/sysdeps/unix/sysv/linux/bits/posix_opt.h index 2339d4a147..435a1bfbe1 100644 --- a/sysdeps/unix/sysv/linux/bits/posix_opt.h +++ b/sysdeps/unix/sysv/linux/bits/posix_opt.h @@ -25,7 +25,10 @@ /* Processes have a saved set-user-ID and a saved set-group-ID. */ #define _POSIX_SAVED_IDS 1 -/* Priority scheduling is supported. */ +/* Priority scheduling is not supported with the correct semantics, + but GNU/Linux applications expect that the corresponding interfaces + are available, even though the semantics do not meet the POSIX + requirements. See glibc bug 14829. */ #define _POSIX_PRIORITY_SCHEDULING 200809L /* Synchronizing file data is supported. */
* Florian Weimer: > * Carlos O'Donell: > >> My preference is to add a trailing "(See bug 14829)", since finding that >> bug helps readers see what's going on. > > Sure. Please see the patch below. > > Thanks, > Florian > > ----- > On Linux, we define _POSIX_PRIORITY_SCHEDULING, but functions such > as sched_setparam and sched_setscheduler apply to individual threads, > not processes. > > 2018-12-14 Florian Weimer <fweimer@redhat.com> > > [BZ #14829] > * manual/resource.texi (Basic Scheduling Functions): Add > portability note. Change process to task throughout the section. > Remove incorrect comment about sched_yield as it affects > tasks/threads, not entire processes. > * sysdeps/unix/sysv/linux/bits/posix_opt.h > (_POSIX_PRIORITY_SCHEDULING): Update comment. Ping? <https://sourceware.org/ml/libc-alpha/2018-12/msg00516.html> Thanks, Florian
On 12/14/18 4:56 PM, Florian Weimer wrote: > * Carlos O'Donell: > >> My preference is to add a trailing "(See bug 14829)", since finding that >> bug helps readers see what's going on. > > Sure. Please see the patch below. > OK for master. Since this is just documentation I think this is OK for the freeze. Reviewed-by: Carlos O'Donell <carlos@redhat.com> > Thanks, > Florian > > ----- > On Linux, we define _POSIX_PRIORITY_SCHEDULING, but functions such > as sched_setparam and sched_setscheduler apply to individual threads, > not processes. > > 2018-12-14 Florian Weimer <fweimer@redhat.com> > > [BZ #14829] > * manual/resource.texi (Basic Scheduling Functions): Add > portability note. Change process to task throughout the section. > Remove incorrect comment about sched_yield as it affects > tasks/threads, not entire processes. > * sysdeps/unix/sysv/linux/bits/posix_opt.h > (_POSIX_PRIORITY_SCHEDULING): Update comment. > > diff --git a/manual/resource.texi b/manual/resource.texi > index 8c4c92a184..60e6d61611 100644 > --- a/manual/resource.texi > +++ b/manual/resource.texi > @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. > > The symbols in this section are declared by including file @file{sched.h}. > > +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the > +functions below refer to process IDs. On Linux, they are actually > +thread IDs, and control how specific threads are scheduled with > +regards to the entire system. The resulting behavior does not conform > +to POSIX. This is why the following description refers to tasks and > +tasks IDs, and not processes and process IDs. OK. > +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 > + > @deftp {Data Type} {struct sched_param} > @standards{POSIX, sched.h} > This structure describes an absolute priority. > @@ -765,11 +773,11 @@ absolute priority value > @c Direct syscall, Linux only. > > This function sets both the absolute priority and the scheduling policy > -for a process. > +for a task. OK. > > It assigns the absolute priority value given by @var{param} and the > -scheduling policy @var{policy} to the process with Process ID @var{pid}, > -or the calling process if @var{pid} is zero. If @var{policy} is > +scheduling policy @var{policy} to the task with ID @var{pid}, > +or the calling task if @var{pid} is zero. If @var{policy} is OK. > negative, @code{sched_setscheduler} keeps the existing scheduling policy. > > The following macros represent the valid values for @var{policy}: > @@ -795,20 +803,20 @@ to this function are: > @item EPERM > @itemize @bullet > @item > -The calling process does not have @code{CAP_SYS_NICE} permission and > +The calling task does not have @code{CAP_SYS_NICE} permission and OK. > @var{policy} is not @code{SCHED_OTHER} (or it's negative and the > existing policy is not @code{SCHED_OTHER}. > > @item > -The calling process does not have @code{CAP_SYS_NICE} permission and its > -owner is not the target process' owner. I.e., the effective uid of the > -calling process is neither the effective nor the real uid of process > +The calling task does not have @code{CAP_SYS_NICE} permission and its > +owner is not the target task's owner. I.e., the effective uid of the > +calling task is neither the effective nor the real uid of task OK. > @var{pid}. > @c We need a cross reference to the capabilities section, when written. > @end itemize > > @item ESRCH > -There is no process with pid @var{pid} and @var{pid} is not zero. > +There is no task with pid @var{pid} and @var{pid} is not zero. OK. > > @item EINVAL > @itemize @bullet > @@ -835,8 +843,8 @@ tell you what the valid range is. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function returns the scheduling policy assigned to the process with > -Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. > +This function returns the scheduling policy assigned to the task with > +ID @var{pid}, or the calling task if @var{pid} is zero. OK. > > The return value is the scheduling policy. See > @code{sched_setscheduler} for the possible values. > @@ -849,7 +857,7 @@ The @code{errno} values specific to this function are: > @table @code > > @item ESRCH > -There is no process with pid @var{pid} and it is not zero. > +There is no task with pid @var{pid} and it is not zero. OK. > > @item EINVAL > @var{pid} is negative. > @@ -869,7 +877,7 @@ absolute priority, use @code{sched_getparam}. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function sets a process' absolute priority. > +This function sets a task's absolute priority. OK. > > It is functionally identical to @code{sched_setscheduler} with > @var{policy} = @code{-1}. > @@ -883,13 +891,13 @@ It is functionally identical to @code{sched_setscheduler} with > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall, Linux only. > > -This function returns a process' absolute priority. > +This function returns a task's absolute priority. OK. > > -@var{pid} is the Process ID (pid) of the process whose absolute priority > -you want to know. > +@var{pid} is the task ID of the task whose absolute priority you want > +to know. OK. > > @var{param} is a pointer to a structure in which the function stores the > -absolute priority of the process. > +absolute priority of the task. OK. > > On success, the return value is @code{0}. Otherwise, it is @code{-1} > and @code{errno} is set accordingly. The @code{errno} values specific > @@ -898,7 +906,7 @@ to this function are: > @table @code > > @item ESRCH > -There is no process with pid @var{pid} and it is not zero. > +There is no task with ID @var{pid} and it is not zero. OK. > > @item EINVAL > @var{pid} is negative. > @@ -914,7 +922,7 @@ There is no process with pid @var{pid} and it is not zero. > @c Direct syscall, Linux only. > > This function returns the lowest absolute priority value that is > -allowable for a process with scheduling policy @var{policy}. > +allowable for a task with scheduling policy @var{policy}. OK. > > On Linux, it is 0 for SCHED_OTHER and 1 for everything else. > > @@ -935,7 +943,7 @@ to this function are: > @c Direct syscall, Linux only. > > This function returns the highest absolute priority value that is > -allowable for a process that with scheduling policy @var{policy}. > +allowable for a task that with scheduling policy @var{policy}. OK. > > On Linux, it is 0 for SCHED_OTHER and 99 for everything else. > > @@ -956,8 +964,8 @@ to this function are: > @c Direct syscall, Linux only. > > This function returns the length of the quantum (time slice) used with > -the Round Robin scheduling policy, if it is used, for the process with > -Process ID @var{pid}. > +the Round Robin scheduling policy, if it is used, for the task with > +task ID @var{pid}. OK. > > It returns the length of time as @var{interval}. > @c We need a cross-reference to where timespec is explained. But that > @@ -980,18 +988,18 @@ function, so there are no specific @code{errno} values. > @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > @c Direct syscall on Linux; alias to swtch on HURD. > > -This function voluntarily gives up the process' claim on the CPU. > +This function voluntarily gives up the task's claim on the CPU. OK. > > -Technically, @code{sched_yield} causes the calling process to be made > +Technically, @code{sched_yield} causes the calling task to be made OK. > immediately ready to run (as opposed to running, which is what it was > before). This means that if it has absolute priority higher than 0, it > -gets pushed onto the tail of the queue of processes that share its > +gets pushed onto the tail of the queue of tasks that share its OK. > absolute priority and are ready to run, and it will run again when its > turn next arrives. If its absolute priority is 0, it is more > complicated, but still has the effect of yielding the CPU to other > -processes. > +tasks. OK. > > -If there are no other processes that share the calling process' absolute > +If there are no other tasks that share the calling task's absolute OK. > priority, this function doesn't have any effect. > > To the extent that the containing program is oblivious to what other > diff --git a/sysdeps/unix/sysv/linux/bits/posix_opt.h b/sysdeps/unix/sysv/linux/bits/posix_opt.h > index 2339d4a147..435a1bfbe1 100644 > --- a/sysdeps/unix/sysv/linux/bits/posix_opt.h > +++ b/sysdeps/unix/sysv/linux/bits/posix_opt.h > @@ -25,7 +25,10 @@ > /* Processes have a saved set-user-ID and a saved set-group-ID. */ > #define _POSIX_SAVED_IDS 1 > > -/* Priority scheduling is supported. */ > +/* Priority scheduling is not supported with the correct semantics, > + but GNU/Linux applications expect that the corresponding interfaces > + are available, even though the semantics do not meet the POSIX > + requirements. See glibc bug 14829. */ OK. Thanks for adding the bug reference. > #define _POSIX_PRIORITY_SCHEDULING 200809L > > /* Synchronizing file data is supported. */ >
diff --git a/manual/resource.texi b/manual/resource.texi index 8bc2a803d4..f02192475a 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -750,6 +750,14 @@ policy, if anything, only fine tunes the effect of that priority. The symbols in this section are declared by including file @file{sched.h}. +@strong{Portability Note:} In POSIX, the @code{pid_t} arguments of the +functions below refer to process IDs. On Linux, they are actually +thread IDs, and control how specific threads are scheduled with +regards to the entire system. The resulting behavior does not conform +to POSIX. This is why the following description refers to tasks and +tasks IDs, and not processes and process IDs. +@c https://sourceware.org/bugzilla/show_bug.cgi?id=14829 + @deftp {Data Type} {struct sched_param} @standards{POSIX, sched.h} This structure describes an absolute priority. @@ -765,11 +773,11 @@ absolute priority value @c Direct syscall, Linux only. This function sets both the absolute priority and the scheduling policy -for a process. +for a task. It assigns the absolute priority value given by @var{param} and the -scheduling policy @var{policy} to the process with Process ID @var{pid}, -or the calling process if @var{pid} is zero. If @var{policy} is +scheduling policy @var{policy} to the task with ID @var{pid}, +or the calling task if @var{pid} is zero. If @var{policy} is negative, @code{sched_setscheduler} keeps the existing scheduling policy. The following macros represent the valid values for @var{policy}: @@ -795,20 +803,20 @@ to this function are: @item EPERM @itemize @bullet @item -The calling process does not have @code{CAP_SYS_NICE} permission and +The calling task does not have @code{CAP_SYS_NICE} permission and @var{policy} is not @code{SCHED_OTHER} (or it's negative and the existing policy is not @code{SCHED_OTHER}. @item -The calling process does not have @code{CAP_SYS_NICE} permission and its -owner is not the target process' owner. I.e., the effective uid of the -calling process is neither the effective nor the real uid of process +The calling task does not have @code{CAP_SYS_NICE} permission and its +owner is not the target task's owner. I.e., the effective uid of the +calling task is neither the effective nor the real uid of task @var{pid}. @c We need a cross reference to the capabilities section, when written. @end itemize @item ESRCH -There is no process with pid @var{pid} and @var{pid} is not zero. +There is no task with pid @var{pid} and @var{pid} is not zero. @item EINVAL @itemize @bullet @@ -835,8 +843,8 @@ tell you what the valid range is. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function returns the scheduling policy assigned to the process with -Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. +This function returns the scheduling policy assigned to the task with +ID @var{pid}, or the calling task if @var{pid} is zero. The return value is the scheduling policy. See @code{sched_setscheduler} for the possible values. @@ -849,7 +857,7 @@ The @code{errno} values specific to this function are: @table @code @item ESRCH -There is no process with pid @var{pid} and it is not zero. +There is no task with pid @var{pid} and it is not zero. @item EINVAL @var{pid} is negative. @@ -869,7 +877,7 @@ absolute priority, use @code{sched_getparam}. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function sets a process' absolute priority. +This function sets a task's absolute priority. It is functionally identical to @code{sched_setscheduler} with @var{policy} = @code{-1}. @@ -883,13 +891,13 @@ It is functionally identical to @code{sched_setscheduler} with @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall, Linux only. -This function returns a process' absolute priority. +This function returns a task's absolute priority. -@var{pid} is the Process ID (pid) of the process whose absolute priority -you want to know. +@var{pid} is the task ID of the task whose absolute priority you want +to know. @var{param} is a pointer to a structure in which the function stores the -absolute priority of the process. +absolute priority of the task. On success, the return value is @code{0}. Otherwise, it is @code{-1} and @code{errno} is set accordingly. The @code{errno} values specific @@ -898,7 +906,7 @@ to this function are: @table @code @item ESRCH -There is no process with pid @var{pid} and it is not zero. +There is no task with ID @var{pid} and it is not zero. @item EINVAL @var{pid} is negative. @@ -914,7 +922,7 @@ There is no process with pid @var{pid} and it is not zero. @c Direct syscall, Linux only. This function returns the lowest absolute priority value that is -allowable for a process with scheduling policy @var{policy}. +allowable for a task with scheduling policy @var{policy}. On Linux, it is 0 for SCHED_OTHER and 1 for everything else. @@ -935,7 +943,7 @@ to this function are: @c Direct syscall, Linux only. This function returns the highest absolute priority value that is -allowable for a process that with scheduling policy @var{policy}. +allowable for a task that with scheduling policy @var{policy}. On Linux, it is 0 for SCHED_OTHER and 99 for everything else. @@ -956,8 +964,8 @@ to this function are: @c Direct syscall, Linux only. This function returns the length of the quantum (time slice) used with -the Round Robin scheduling policy, if it is used, for the process with -Process ID @var{pid}. +the Round Robin scheduling policy, if it is used, for the task with +task ID @var{pid}. It returns the length of time as @var{interval}. @c We need a cross-reference to where timespec is explained. But that @@ -980,18 +988,18 @@ function, so there are no specific @code{errno} values. @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c Direct syscall on Linux; alias to swtch on HURD. -This function voluntarily gives up the process' claim on the CPU. +This function voluntarily gives up the task's claim on the CPU. -Technically, @code{sched_yield} causes the calling process to be made +Technically, @code{sched_yield} causes the calling task to be made immediately ready to run (as opposed to running, which is what it was before). This means that if it has absolute priority higher than 0, it -gets pushed onto the tail of the queue of processes that share its +gets pushed onto the tail of the queue of tasks that share its absolute priority and are ready to run, and it will run again when its turn next arrives. If its absolute priority is 0, it is more complicated, but still has the effect of yielding the CPU to other -processes. +tasks. -If there are no other processes that share the calling process' absolute +If there are no other tasks that share the calling task's absolute priority, this function doesn't have any effect. To the extent that the containing program is oblivious to what other