manual: Document lack of conformance of sched_* functions [BZ #14829]

Message ID 87sgz9fq53.fsf@oldenburg2.str.redhat.com
State New
Headers show
Series
  • manual: Document lack of conformance of sched_* functions [BZ #14829]
Related show

Commit Message

Florian Weimer Dec. 7, 2018, 1 p.m.
On Linux, we define _POSIX_PRIORITY_SCHEDULING, but functions such
as sched_setparam and sched_setscheduler apply to individual threads,
not processes.

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.

Comments

Carlos O'Donell Dec. 14, 2018, 8:55 p.m. | #1
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

> 



-- 
Cheers,
Carlos.
Florian Weimer Dec. 14, 2018, 9:08 p.m. | #2
* 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
Carlos O'Donell Dec. 14, 2018, 9:15 p.m. | #3
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.

-- 
Cheers,
Carlos.
Florian Weimer Dec. 14, 2018, 9:56 p.m. | #4
* 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 Jan. 9, 2019, 12:30 p.m. | #5
* 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
Carlos O'Donell Jan. 9, 2019, 4:14 p.m. | #6
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.  */

> 



-- 
Cheers,
Carlos.

Patch

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