Debian Bug report logs - #540872
clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Toggle useless messages

Message #3 received at submit@bugs.debian.org (full text, mbox, reply):

From: Josh Triplett <josh@joshtriplett.org>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Mon, 10 Aug 2009 11:30:34 -0700

Package: manpages
Version: 3.22-1
Severity: wishlist

Developers of real-time programs (programs using real-time scheduling
and/or expecting low latency) sometimes see CLOCK_REALTIME and think
they want to use that, when they almost certainly don't.  Please
consider adding some clarification that the "real-time" of
CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
time, for instance) and that developers of real-time applications want
to use CLOCK_MONOTONIC.

Thanks,
Josh Triplett

-- System Information:
Debian Release: squeeze/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: i386 (i686)

Kernel: Linux 2.6.31-rc5 (SMP w/2 CPU cores; PREEMPT)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash

manpages depends on no packages.

manpages recommends no packages.

Versions of packages manpages suggests:
ii  man-db [man-browser]          2.5.5-3    on-line manual pager

-- no debconf information

Message #8 received at 540872@bugs.debian.org (full text, mbox, reply):

From: Simon Paillard <spaillard@debian.org>

To: Josh Triplett <josh@joshtriplett.org>, 540872@bugs.debian.org

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Sun, 29 Apr 2012 00:21:15 +0200

tags + upstream
thanks

Hi,

On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> Package: manpages
> Version: 3.22-1
> Severity: wishlist
> 
> Developers of real-time programs (programs using real-time scheduling
> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> they want to use that, when they almost certainly don't.  Please
> consider adding some clarification that the "real-time" of
> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> time, for instance) and that developers of real-time applications want
> to use CLOCK_MONOTONIC.

Michael Kerrisk improved clock_getres.2 in manpages 3.40: 

 .B CLOCK_MONOTONIC
 Clock that cannot be set and represents monotonic time since
 some unspecified starting point.
+This clock is not affected by discontinuous jumps in the system time
+(e.g., if the system administrator manually changes the clock),
+but is affected by the incremental adjustments performed by
+.BR adjtime (2)
+and NTP.

Maybe one can add (please proofread my english):
"This clock allow to precisely measuring time elapsed, for use in real-time programs."

http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html

-- 
Simon Paillard

Message #15 received at 540872@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

To: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org

Cc: Josh Triplett <josh@joshtriplett.org>

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Sun, 29 Apr 2012 22:40:48 +1200

On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> tags + upstream
> thanks
>
> Hi,
>
> On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
>> Package: manpages
>> Version: 3.22-1
>> Severity: wishlist
>>
>> Developers of real-time programs (programs using real-time scheduling
>> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
>> they want to use that, when they almost certainly don't.  Please
>> consider adding some clarification that the "real-time" of
>> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
>> time, for instance) and that developers of real-time applications want
>> to use CLOCK_MONOTONIC.
>
> Michael Kerrisk improved clock_getres.2 in manpages 3.40:
>
>  .B CLOCK_MONOTONIC
>  Clock that cannot be set and represents monotonic time since
>  some unspecified starting point.
> +This clock is not affected by discontinuous jumps in the system time
> +(e.g., if the system administrator manually changes the clock),
> +but is affected by the incremental adjustments performed by
> +.BR adjtime (2)
> +and NTP.
>
> Maybe one can add (please proofread my english):
> "This clock allow to precisely measuring time elapsed, for use in real-time programs."
>
> http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html

Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Message #20 received at 540872@bugs.debian.org (full text, mbox, reply):

From: Josh Triplett <josh@joshtriplett.org>

To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Sun, 29 Apr 2012 12:15:08 -0700

On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> > tags + upstream
> > thanks
> >
> > Hi,
> >
> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> >> Package: manpages
> >> Version: 3.22-1
> >> Severity: wishlist
> >>
> >> Developers of real-time programs (programs using real-time scheduling
> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> >> they want to use that, when they almost certainly don't.  Please
> >> consider adding some clarification that the "real-time" of
> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> >> time, for instance) and that developers of real-time applications want
> >> to use CLOCK_MONOTONIC.
> >
> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
> >
> >  .B CLOCK_MONOTONIC
> >  Clock that cannot be set and represents monotonic time since
> >  some unspecified starting point.
> > +This clock is not affected by discontinuous jumps in the system time
> > +(e.g., if the system administrator manually changes the clock),
> > +but is affected by the incremental adjustments performed by
> > +.BR adjtime (2)
> > +and NTP.
> >
> > Maybe one can add (please proofread my english):
> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
> >
> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
> 
> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?

Probably, yes.

Ideally, I'd also like to see something like this added to the
description of CLOCK_REALTIME, to help avert a common trap people fall
into:

'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
not to suitability for realtime (latency-sensitive) applications.  Such
applications generally want to use CLOCK_MONOTONIC or
CLOCK_MONOTONIC_RAW.'

- Josh Triplett

Message #25 received at 540872@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

To: Josh Triplett <josh@joshtriplett.org>

Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Mon, 30 Apr 2012 10:50:50 +1200

tags 540872 fixed-upstream
thanks

Hi Josh!

On Mon, Apr 30, 2012 at 7:15 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
>> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
>> > tags + upstream
>> > thanks
>> >
>> > Hi,
>> >
>> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
>> >> Package: manpages
>> >> Version: 3.22-1
>> >> Severity: wishlist
>> >>
>> >> Developers of real-time programs (programs using real-time scheduling
>> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
>> >> they want to use that, when they almost certainly don't.  Please
>> >> consider adding some clarification that the "real-time" of
>> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
>> >> time, for instance) and that developers of real-time applications want
>> >> to use CLOCK_MONOTONIC.
>> >
>> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
>> >
>> >  .B CLOCK_MONOTONIC
>> >  Clock that cannot be set and represents monotonic time since
>> >  some unspecified starting point.
>> > +This clock is not affected by discontinuous jumps in the system time
>> > +(e.g., if the system administrator manually changes the clock),
>> > +but is affected by the incremental adjustments performed by
>> > +.BR adjtime (2)
>> > +and NTP.
>> >
>> > Maybe one can add (please proofread my english):
>> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
>> >
>> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
>>
>> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?
>
> Probably, yes.
>
> Ideally, I'd also like to see something like this added to the
> description of CLOCK_REALTIME, to help avert a common trap people fall
> into:
>
> 'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
> not to suitability for realtime (latency-sensitive) applications.  Such
> applications generally want to use CLOCK_MONOTONIC or
> CLOCK_MONOTONIC_RAW.'

How about doing this in a different way. Instead of pointing the
reader at CLOCK_MONOTONIC*, let's be more explicit about what
CLOCK_REALTIME is, so that it's evident to the designer of a realtime
application that they don't want this clock.

[[
.TP
.B CLOCK_REALTIME
System-wide clock that measures real (i.e., wall-clock) time.
Setting this clock requires appropriate privileges.
This clock is affected by discontinuous jumps in the system time
(e.g., if the system administrator manually changes the clock),
and by the incremental adjustments performed by
.BR adjtime (2)
and NTP.
]]

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Message #30 received at 540872@bugs.debian.org (full text, mbox, reply):

From: Josh Triplett <josh@joshtriplett.org>

To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>

Cc: Simon Paillard <spaillard@debian.org>, 540872@bugs.debian.org

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Sun, 29 Apr 2012 17:41:23 -0700

On Mon, Apr 30, 2012 at 10:50:50AM +1200, Michael Kerrisk (man-pages) wrote:
> tags 540872 fixed-upstream
> thanks
> 
> Hi Josh!
> 
> On Mon, Apr 30, 2012 at 7:15 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> > On Sun, Apr 29, 2012 at 10:40:48PM +1200, Michael Kerrisk (man-pages) wrote:
> >> On Sun, Apr 29, 2012 at 10:21 AM, Simon Paillard <spaillard@debian.org> wrote:
> >> > tags + upstream
> >> > thanks
> >> >
> >> > Hi,
> >> >
> >> > On Mon, Aug 10, 2009 at 11:30:34AM -0700, Josh Triplett wrote:
> >> >> Package: manpages
> >> >> Version: 3.22-1
> >> >> Severity: wishlist
> >> >>
> >> >> Developers of real-time programs (programs using real-time scheduling
> >> >> and/or expecting low latency) sometimes see CLOCK_REALTIME and think
> >> >> they want to use that, when they almost certainly don't.  Please
> >> >> consider adding some clarification that the "real-time" of
> >> >> CLOCK_REALTIME refers to wall-clock time (as opposed to CPU or process
> >> >> time, for instance) and that developers of real-time applications want
> >> >> to use CLOCK_MONOTONIC.
> >> >
> >> > Michael Kerrisk improved clock_getres.2 in manpages 3.40:
> >> >
> >> >  .B CLOCK_MONOTONIC
> >> >  Clock that cannot be set and represents monotonic time since
> >> >  some unspecified starting point.
> >> > +This clock is not affected by discontinuous jumps in the system time
> >> > +(e.g., if the system administrator manually changes the clock),
> >> > +but is affected by the incremental adjustments performed by
> >> > +.BR adjtime (2)
> >> > +and NTP.
> >> >
> >> > Maybe one can add (please proofread my english):
> >> > "This clock allow to precisely measuring time elapsed, for use in real-time programs."
> >> >
> >> > http://pubs.opengroup.org/onlinepubs/009604599/functions/clock_getres.html
> >>
> >> Simon, would that text not better apply to CLOCK_MONOTONIC_RAW?
> >
> > Probably, yes.
> >
> > Ideally, I'd also like to see something like this added to the
> > description of CLOCK_REALTIME, to help avert a common trap people fall
> > into:
> >
> > 'The "realtime" in the name CLOCK_REALTIME refers to wall-clock time,
> > not to suitability for realtime (latency-sensitive) applications.  Such
> > applications generally want to use CLOCK_MONOTONIC or
> > CLOCK_MONOTONIC_RAW.'
> 
> How about doing this in a different way. Instead of pointing the
> reader at CLOCK_MONOTONIC*, let's be more explicit about what
> CLOCK_REALTIME is, so that it's evident to the designer of a realtime
> application that they don't want this clock.
> 
> [[
> .TP
> .B CLOCK_REALTIME
> System-wide clock that measures real (i.e., wall-clock) time.
> Setting this clock requires appropriate privileges.
> This clock is affected by discontinuous jumps in the system time
> (e.g., if the system administrator manually changes the clock),
> and by the incremental adjustments performed by
> .BR adjtime (2)
> and NTP.
> ]]

Works for me.

- Josh Triplett

Message #35 received at 540872-done@bugs.debian.org (full text, mbox, reply):

From: Simon Paillard <spaillard@debian.org>

To: 540872-done@bugs.debian.org

Subject: Re: Bug#540872: clock_gettime(2): Document that real-time processes want CLOCK_MONOTONIC, not CLOCK_REALTIME

Date: Mon, 22 Oct 2012 00:45:10 +0200

Version: 3.42-1

On Mon, Apr 30, 2012 at 10:50:50AM +1200, Michael Kerrisk (man-pages) wrote:
> tags 540872 fixed-upstream
> thanks
[..] 
> How about doing this in a different way. Instead of pointing the
> reader at CLOCK_MONOTONIC*, let's be more explicit about what
> CLOCK_REALTIME is, so that it's evident to the designer of a realtime
> application that they don't want this clock.
> 
> [[
> .TP
> .B CLOCK_REALTIME
> System-wide clock that measures real (i.e., wall-clock) time.
> Setting this clock requires appropriate privileges.
> This clock is affected by discontinuous jumps in the system time
> (e.g., if the system administrator manually changes the clock),
> and by the incremental adjustments performed by
> .BR adjtime (2)
> and NTP.
> ]]

http://git.kernel.org/?p=docs/man-pages/man-pages.git;a=commitdiff;h=22594a3cb
first in upstream 3.41, and first in debian through manpages 3.42-1.
 

-- 
Simon Paillard

Send a report that this bug log contains spam.