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

[Carlos O'Donell <carlos@redhat.com>]

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.