periodic 'at'

Garrett Smith g at rrett.us.com
Wed Feb 25 16:41:41 CET 2009


----- "Marc Lehmann" <schmorp at schmorp.de> wrote:

> On Tue, Feb 24, 2009 at 08:38:42PM -0600, Garrett Smith
> <g at rrett.us.com> wrote:
>> First, I think the documentation is a bit off -- it uses some of
>> the terms used by timers (after and repeat). Not a biggie. 
> 
> It seems this is only in the shown prototype of ev_periodic_set,
> right? Other uses of the terms seem to be correct.

Yes, that's right. It was off only a very wee bit :)

>> The docs seem to imply that the 'at' argument used in
>> ev_periodic_init can be used to start the periodic at some point 
>> in the future: 
> 
> This depends on the mode, as documented (there are three modes, only
> the absolute timer mode does this).
> 
>> Looking in the source, though, it looks like 'at' is a calculated
>> value that isn't used in the init. The 'at' argument is actually
>> used for 'offset'. The behavior that I've seen supports the source
>> :)
> 
> What do you mean with that? There is no "offset" argument in the
> source, there is only an offset member in the watcher, and that one 
> seems to be documented correctly.

#define ev_periodic_set(ev,ofs_,ival_,res_)
  ...
 (ev)->offset = (ofs_);
  ...

In the online docs, the position arg for ofs_ (offset) is named
'after', but that's a typo. As it ends up in the struct as 'offset',
I'd assume it'd be named 'offset', but I'm not sure, thus confused.

> But "at" and "offset" are different things - one is the argument to
> ev_periodic_init, the other is a struct member - different names,
> different locations, different purposes.

This is confusing.

The input to the init function is named 'at' -- this ends up in the
offset member.

The input to the set function is named 'ofs_' -- I'm not sure what
this will be named in the docs. I'd recommend 'offset', however (see below).

The function ev_periodic_at returns the next scheduled 'at' -- this
is the 'at' in the struct.

I think this is a just docs issue.

IMO, I think the API would be clearer if you stuck with "offset" for
the init and set functions -- staying clear of "at". You can refer to
the offset as being absolute (as in the simple case) or relative (as
in the repeating case).

The only use of "at" is then the ev_periodic_at function, which
provides a read-only "absolute offset" for the next scheduled event.

This is just a thought.

>> Should it be possible to provide both 'at' and 'offset'?
> 
> Towards what end?
> 
>> Without getting into the manual mode, it would be useful to
>> schedule a repeating timer to fire at some point in the future.
> 
> You can do that already without manual mode - you can reprogram the
> periodic as you want, if the existing mdoes are not enough.
>
> Having a completely different starting point and offset is not
> implemented and would require more members (to store this extra
> starting point) and an ABI change. It would also complicate usage of
> the periodics further.

Agreed. I think clarifying the init/set API would clearly dispel any
notion that an absolute offset ('at') can somehow be used with a
relative/repeating offset.

Thanks for the clarification.

Btw, the timer and periodic watchers are a fantastic components of this
library. I'm using them as the foundation for a replacement to a lot of
bloated and sloppy monitoring code. It's sooo nice to be able to execute
at consistent intervals. I'm seeing the watchers fire within a few
milliseconds of the theoretical target on a consistent basis -- very
impressive!

Garrett



More information about the libev mailing list