Re: RFC: A revised timerfd API

Michael Kerrisk
2007-09-22T13:15:38Z

Davide, Andrew, Linus, et al.

At the start of this thread
(http://thread.gmane.org/gmane.linux.kernel/581115 ), I proposed 4
alternatives to Davide's original timerfd API. Based on the feedback in
that thread (and one or two earlier comments):

Let's dismiss option (a), since it is an unlovely multiplexing interface.

Option (b) seems a viable. The most notable concern was from Thomas
Gleixner, that we might end up duplicating code from the POSIX timers API
within the timerfd API -- some eventual refactoring might mitigate this
problem.

Option (c) seems overly complex. In addition, David Härdeman pointed out
that option (c) (and, I realised afterwards, option (d)) require the
userland programmer to maintain a mapping between timerfd file descriptors
and POSIX timer IDs. Thomas Gleixner proposed an API that: attempts to
avoid that problem; mixes features of options (c) and (d); and probably
helps avoid redundancy of kernel code between the timerfd system and the
POSIX timers system. I'll flesh out that API now as I understand it:

====> e) Integrate timerfd() with the POSIX timers API in such a way that
the POSIX timers API understands timerfd file descriptors.

Under the POSIX timers API, a new timer is created using:

int timer_create(clockid_t clockid, struct sigevent *evp,
timer_t *timerid);

When making this call, we would specify evp.sigev_notify to a new flag
value SIGEV_TIMERFD, to inform the system that this timer will deliver
notification via a timerfd file descriptor.

We would then have a timerfd() call that returns a file descriptor
for the newly created 'timerid':

fd = timerfd(timer_t timerid);

(A variant here would be to have timer_create() directly return a file
descriptor when SIGEV_TIMERFD is specified, although this breaks the
traditional semantics that timer_create() only returns 0 on success.)

We could then use the POSIX timers API to operate on the timer
(start it / modify it / fetch timer value):

int timer_settime(timer_t timerid, int flags,
const struct itimerspec *value,
struct itimerspec *ovalue);
int timer_gettime(timer_t timerid, struct itimerspec *value);

The difference here is that 'timerid' could be either:

1) the timerid value returned from timer_create(); or

2) the value (fd | POSIX_TIMER_FD), where POSIX_TIMER_FD is a
flag (perhaps the topmost bit set on) that indicates that
the rest of the value is a file descriptor. With this
information, the kernel can do a lookup to find the
corresponding timerfd and perform the required operation
on it.

Advantages:
1. Userland programs don't need to maintain a mapping between
timer IDs and file descriptors.
2. Adds just a single system call.

Disadvantages:
1. This design stretches the POSIX timers API in strange
ways. My option (d) also did this to a lesser extent,
and that felt slightly uncomfortable. Option (e)
makes more uncomfortable still. As David Härdeman
pointed out, overloading file descriptors with flags looks
ugly, and I can't thing of any other syscall that does
that. In addition this idea probably breaks POSIX, since
'timer_t' is only required to be an arithmetic type: it
need not specifically be an integer type (although it is
on Linux).

=====

The upshot is that of the 5 alternatives, I favor option (b). David
Härdeman also expressed a preference for option (b) and it was Davide's
least disliked alternative ;-).

So I'm inclined to implement option (b), unless someone has strong
objections. Davide, could I persuade you to help?

Cheers,

Michael

--
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance? Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.