periodic 'at'

Garrett Smith g at rrett.us.com
Wed Feb 25 21:48:45 CET 2009


I looked at the source because the docs had a typo and I was trying
to understand what was going on.

I don't need lectures about reading the docs. There was an error in
those docs, and so the question.

I'm not complaining about anything here. I'm a huge fan of your work
and have nothing but positive things to say about it. I take great
pains to be constructive and respectful in any correspondence and
certainly have done so with you.

Chill the *bleep* out Marc -- your animosity is totally uncalled for.

Garrett

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

> 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