Re: [Libevent-users] Proposal for libevent-2 to provide functions to hide event structure details

[Nick Mathewson <nickm@xxxxxxxxxxxxx>]

On Fri, Jan 15, 2010 at 6:22 AM, Dan Kegel <dank@xxxxxxxxx> wrote:
> On Fri, Jan 15, 2010 at 2:48 AM, Pavel Pisa <ppisa4lists@xxxxxxxxxx> wrote:
>> please, consider addition of functions to allow access more fields
>> of struct event a way ensuring compatibility with future libevent version.
>> ...
>> The rationale:
>>  - hide event structure implementation/layout. Application using these
>> functions instead of direct access can keep compatibility with future libevent
>> versions.
>
> +1
>
> I for one would love to see libevent have a stable ABI, and that means no
> more public structs.   (I had hoped they'd be gone with 2.0.)

Since you mentioned, I'll explain. :)

Because a lot of old code uses them, we can't remove the public
structs entirely.  However, we have relegated them to separate header
files, and added new APIs that make it unnecessary to ever use them.

The general rule is that old header names like "event.h" will still
work the same.  (We try not to break source compatibility with stable
versions.)  If you include "event2/event.h" you will get only
non-deprecated, non-ABI-destabilizing interfaces.  If you include
"event2/event_compat.h" you will get the deprecated interfaces that
you might need to make old code run, and if you include
"event2/event_struct.h" you will get the public structs.

The big offender was of course "struct event".  If you ever wrote code
that did something innocuous like:

   struct event *e = malloc(sizeof(struct event));
   if (!e) die horribly();
   event_set(e, fd, EV_READ, read_cb, read_cb_arg);
   event_set_base(e, base);

then you probably knew some ABI pain, since if the size of struct
event ever grew, your program would stomp the heap.

The preferred solution that most programs should use when using Libevent 2.0 is:

  struct event *e = event_new(event_base, fd, EV_READ, read_cb, read_cb_arg);

This way they don't need to worry about the size of struct event, or
the layout of its members, at all.

Pavel's point as I understand it is that event_new, since it does a
malloc of its own, is not so great for applications that want to embed
a struct event in another structure, or that want to allocate a big
array of struct event.  For most programs, event_new should be good
enough.  But for ones that really need to optimize their memory layout
by doing allocation themselves, it would be helpful to be able to know
_at runtime_ how much memory to allocate for a struct event.

-- 
Nick
***********************************************************************
To unsubscribe, send an e-mail to majordomo@xxxxxxxxxxxxx with
unsubscribe libevent-users    in the body.