Suggestion for libev man page

MONGIOVI, ROY rx5330 at
Mon Jan 16 16:26:29 CET 2017

At the start of the section you mention that there's a void *data field.  But in your examples you don't use it.  So fine.  I can be expected, I suppose, to know that I can allocate an arbitrary block of data and save the pointer to it, or if my data is small enough to fit in a void * I can type pun the data field itself.

You've got an example where the address of the watcher is the same as the address of the containing structure (i.e. offsetof is 0), and an example where you use offsetof to compute back to the address of the containing structure from the watcher address.  Both of those examples leave the data field unused.  If the user wants to use it for other things that's fine, but if not then why not use it to find the container address?  It's clear and shouldn't cause the guy who inherits the code from you to scratch his head and wonder why you're doing that pointer math.

Just init the watcher and then set its data field to point to the containing structure.  Then each watcher in the structure just has to cast the data pointer back to the container type.  It's clear and has effectively no cost since that data pointer is sitting there doing nothing anyway.  And since you mention "extra speed", a type cast costs nothing at execution time.  The pointer math with offsetof takes time on every watcher invocation.  Setting the data pointer to the address of the container happens only when the watcher is initialized.

It's just an idea for your examples section.  Worth every penny it cost you.

-----Original Message-----
From: Marc Lehmann [mailto:schmorp at] 
Sent: Saturday, January 14, 2017 11:59 AM
To: MONGIOVI, ROY <rx5330 at>
Cc: libev at
Subject: Re: Suggestion for libev man page

On Fri, Jan 13, 2017 at 07:49:14PM +0000, "MONGIOVI, ROY" <rx5330 at> wrote:
> In the section titled "Building your own composite watchers" the man page suggests putting several watchers in a single structure and then using offsetof within each watcher to compute back to the beginning of the containing structure.  That seems overly obscure to me, not to mention that it makes the code extremely fragile to changes in the containing structure.  I think that this is an unnecessary complication.

Something being obscure to you is, unfortunately, not a good reason to change things - libev *is* a pretty low level C library, and good knowledge of C is required. The libev manpage should be a lot of things, but not a basic C tutorial.

More importantly, why would it be fragile to changes in the containing structure?

Lastly, the subject of your mail, says there is a suggestion, but in the body you don't seem to have a suggestion - what is it that you suggest.

> Each watcher already has a void *data variable allocated which in this 
> example is unused.  Just store a pointer to the containing structure 
> in each watcher's data variable

Yes, this is actually explained in the very section you talk about. What about it did you find lacking, if anything?

> That's much clearer than offsetof.

That's your (valid) opinion, and in fact, the documentation documents this as a valid option. It is not the only option, however, and some people are concerned more about the extra speed than some specific sense of aesthetics. That's why both ways are supported and documented.


                The choice of a       Deliantra, the free code+content MORPG
      -----==-     _GNU_    
      ----==-- _       generation
      ---==---(_)__  __ ____  __      Marc Lehmann
      --==---/ / _ \/ // /\ \/ /      schmorp at
      -=====/_/_//_/\_,_/ /_/\_\

More information about the libev mailing list