periodic 'at'

Marc Lehmann schmorp at schmorp.de
Wed Feb 25 21:29:18 CET 2009


On Wed, Feb 25, 2009 at 09:41:41AM -0600, Garrett Smith <g at rrett.us.com> wrote:
> 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.

Well, you are looking at undocumented, internal implementation details. If it
confuses you, then I am sorry to say so, that's not my or libev's problem -
libev has a wealth of documentation, and the documentation for the offste
member should explain what it does and what it does not.

> > 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.

Well, learn programming then. Sorry to be so blunt, but if C code confuses
you, that's your issue. The public API doesn't suffer from that confusion
problem. It's only your interpretation of the implementatioon that
confuses you.

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

Again, that's an undocumented implementation detail. If it bothers you, stick
to the public API.

> 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 input to the set function is named "at" (now) or after (before), not
_ofs. Again, you are talking about undocumented and internal code that is not
part odf the public API.

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

No, it is not. Neither the documentation claims this, nor does it work in
practise. Accessing the at member in the struct will not give you the at
value - there is a documented accessor called "ev_periodic_at" that accesses
the real at value.

Again, you are talking about undocumented details that are subject to change.
Stick to the documented API if you find it confusing.

> I think this is a just docs issue.

No, the docs don't mention anything of what you claim they do.

> 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 problem is that you look at the code, not the API, and then confuse it
with the API. The API is clearly documented in the documentation, not in
the implementation files.

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

Ignoring the documentation and accessing internal members of watchers makes
your program buggy. Either stick to the API or complain to yourself. The API
does (deliberatly) not document any "at" member, because there isn't one that
is used by libev itself - there is a documented accessor for it.

-- 
                The choice of a       Deliantra, the free code+content MORPG
      -----==-     _GNU_              http://www.deliantra.net
      ----==-- _       generation
      ---==---(_)__  __ ____  __      Marc Lehmann
      --==---/ / _ \/ // /\ \/ /      pcg at goof.com
      -=====/_/_//_/\_,_/ /_/\_\



More information about the libev mailing list