Re: git: bf8f6ffcb66a - main - Mention kern.timecounter.alloweddeviation in nanosleep.1

On Sat, 9 Oct 2021 09:43:34 +0300
Konstantin Belousov <kostikbel@gmail.com> wrote:

> On Sat, Oct 09, 2021 at 06:18:48AM +0000, Piotr P. Stefaniak wrote:
> > On 2021-10-09 08:53:08, Konstantin Belousov wrote:  
> > > On Fri, Oct 08, 2021 at 03:09:04PM +0000, Piotr Pawel Stefaniak wrote:  
> > > > @@ -93,6 +93,8 @@ returns immediately and the calling thread is not suspended.
> > > >  .Pp
> > > >  The suspension time may be longer than requested due to the
> > > >  scheduling of other activity by the system.
> > > > +It is also subject to the allowed time interval deviation
> > > > +specified by the sysctl kern.timecounter.alloweddeviation.  
> > > This should be like
> > > .Xr sysctl 3
> > > .Dv kern.timecounter.alloweddeviation  
> > 
> > @@ -94,7 +94,9 @@ returns immediately and the calling thread is not suspended.
> >  The suspension time may be longer than requested due to the
> >  scheduling of other activity by the system.
> >  It is also subject to the allowed time interval deviation
> > -specified by the sysctl kern.timecounter.alloweddeviation.
> > +specified by the
> > +.Xr sysctl 3
> > +.Dv kern.timecounter.alloweddeviation .
> >  An unmasked signal will terminate the sleep early, regardless of the
> >  .Dv SA_RESTART
> >  value on the interrupting signal.
> >   
> > > And then, it is missing a description what exactly is allowed by deviation,
> > > for instance, what units this sysctl is?  
> > 
> > That would be redundant with sysctl -d. The point of this change is that now
> > the user is much more likely to know of the sysctl and can look it up and read
> > all about it.
> >   
> sysctl -d is not a (good) documentation.  When you read a man text, you are
> supposed to get everything that is relevant there, although it might be
> terse and requiring making logical deduction.  This is not the case there.
> 
> Anyway, I went ahead and did what you suggested.  On one of my machines,
> I got
> solo% sysctl -d kern.timecounter.alloweddeviation
> kern.timecounter.alloweddeviation: 
> solo%
> 
> On another,
> v1%  sysctl -d kern.timecounter.alloweddeviation                              ~
> kern.timecounter.alloweddeviation: Allowed time interval deviation in percents
> 
> Slightly more useful, but still.  Percents of what?
> 

I wondered about that myself when I looked at it yesterday.

Just to be pedantic, percent is a contraction of per centum and does
not have a plural form.  It's always percent.

> Imagine somebody reads the man page in the browser from Linux.  Where should
> he search for the sysctl description?
> 
> > The bug may be that there isn't much documentation to be read about it, only
> > sysctl -d and kern_tc.c.
> > 
> > The only thing I worry that may be missing from this change is this reference
> > in any other manual pages that might need it as much as nanosleep.  
> Well, nanosleep is just an example of a syscall requesting timeout.
> Another poster childs there are select(2), and poll(2) family which
> explicitly use precision.
> 
> To get the definitive list, you would need to review all uses of
> callout_reset() variants.
> 


-- 
Gary Jennejohn