Re: Man page for revised timerfd API

[Matti Aarnio <matti.aarnio@zmailer.org>]

On Wed, Oct 03, 2007 at 08:50:09AM +0200, Michael Kerrisk wrote:
> Davide Libenzi wrote:
> > On Thu, 27 Sep 2007, Michael Kerrisk wrote:
> > 
> >> Davide,
> >>
> >> A further question: what is the expected behavior in the
> >> following scenario:
> >>
> >> 1. Create a timerfd and arm it.
> >> 2. Wait until M timer expirations have occurred
> >> 3. Modify the settings of the timer
> >> 4. Wait for N further timer expirations have occurred
> >> 5. read() from the timerfd
> >>
> >> Does the buffer returned by the read() contain the value
> >> N or (M+N)?  In other words, should modifying the timer
> >> settings reset the expiration count to zero?
> > 
> > Every timerfd_settime() zeroes the tick counter. So in your scenario it'll 
> > return N.
> 
> Thanks Davide.
> 
> I modified the first para of the read description to make this clear:
> 
>        read(2)
>               If the timer has already expired one or more times
>               since   its  settings  were  last  modified  using
>               timerfd_settime(), or since  the  last  successful
>               read(2),  then the buffer given to read(2) returns
>               an unsigned 8-byte integer  (uint64_t)  containing
>               the number of expirations that have occurred.

When returning multi-byte long numeric values via read(2) as byte streams,
my default question is:

   Can you explicitely state what is the byte order ?

It _probably_ is the host-byte-order as kernel- and userspaces can hardly
run with different ones and this does not sound like an API to be used
over the network, but nevertheless...


In the code-example:

    for (tot_exp = 0; tot_exp < max_exp;) {
        s = read(fd, &exp, sizeof(uint64_t));
        if (s != sizeof(uint64_t))
            die("read");
        tot_exp += exp;
        print_elapsed_time();
        printf("read: %llu; total=%d\\n", exp, tot_exp);
    }

If I may suggest some alterations:

    for (tot_exp = 0; tot_exp < max_exp;) {
        s = read(fd, &exp, sizeof(exp));
        if (s < 0) {
            /* add: EINTR etc. processing */
            continue;
        }
        if (s != sizeof(exp))
            die("read");
        tot_exp += exp;
        print_elapsed_time();
        printf("read: %lu; total=%d\\n", (unsigned long) exp, tot_exp);
    }

The "die if surprised" -strategy is not nice.
Somebody will take example out of that code.

Indeed defining all possible error modes may be impossible, but it may
be possible to define those errors that result in so severe dysfunction
that closing and re-creating the timer-handle may be your only choice.
(About the impossibility:  Solaris STREAMS based network accept() does/did
 yield all kinds of odd errors out from the STREAMS stack in addition to
 those listed in the syscall man-page.  Reacting on all unknown errors
 by dying is not really a smart thing on a program.)


> (In the earlier version of the page the text talked about expirations
> "since the timer was created".)
> 
> Cheers,
> 
> Michael
> -- 
> Michael Kerrisk
> maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

  /Matti Aarnio  <matti.aarnio@zmailer.org>