1 What's new in Libevent 2.1
6 0.1. About this document
8 This document describes the key differences between Libevent 2.0 and
9 Libevent 2.1, from a user's point of view. It's a work in progress.
11 For better documentation about libevent, see the links at
14 Libevent 2.1 would not be possible without the generous help of
15 numerous volunteers. For a list of who did what in Libevent 2.1,
16 please see the ChangeLog!
18 NOTE: I am very sure that I missed some thing on this list. Caveat
21 0.2. Where to get help
23 Try looking at the other documentation too. All of the header files
24 have documentation in the doxygen format; this gets turned into nice
25 HTML and linked to from the libevent.org website.
27 There is a work-in-progress book with reference manual at
28 http://www.wangafu.net/~nickm/libevent-book/ .
30 You can ask questions on the #libevent IRC channel at irc.oftc.net or
31 on the mailing list at libevent-users@freehaven.net. The mailing list
32 is subscribers-only, so you will need to subscribe before you post.
36 Our source-compatibility policy is that correct code (that is to say,
37 code that uses public interfaces of Libevent and relies only on their
38 documented behavior) should have forward source compatibility: any
39 such code that worked with a previous version of Libevent should work
40 with this version too.
42 We don't try to do binary compatibility except within stable release
43 series, so binaries linked against any version of Libevent 2.0 will
44 probably need to be recompiled against Libevent 2.1.4-alpha if you
45 want to use it. It is probable that we'll break binary compatibility
46 again before Libevent 2.1 is stable.
48 1. New APIs and features
50 1.1. New ways to build libevent
52 We now provide an --enable-gcc-hardening configure option to turn on
53 GCC features designed for increased code security.
55 There is also an --enable-silent-rules configure option to make
56 compilation run more quietly with automake 1.11 or later.
58 You no longer need to use the --enable-gcc-warnings option to turn on
59 all of the GCC warnings that Libevent uses. The only change from
60 using that option now is to turn warnings into errors.
62 For IDE users, files that are not supposed to be built are now
63 surrounded with appropriate #ifdef lines to keep your IDE from getting
66 There is now an alternative cmake-based build process; cmake users
67 should see the relevant sections in the README.
70 1.2. New functions for events and the event loop
72 If you're running Libevent with multiple event priorities, you might
73 want to make sure that Libevent checks for new events frequently, so
74 that time-consuming or numerous low-priority events don't keep it from
75 checking for new high-priority events. You can now use the
76 event_config_set_max_dispatch_interval() interface to ensure that the
77 loop checks for new events either every N microseconds, every M
80 When configuring an event base, you can now choose whether you want
81 timers to be more efficient, or more precise. (This only has effect
82 on Linux for now.) Timers are efficient by default: to select more
83 precise timers, use the EVENT_BASE_FLAG_PRECISE_TIMER flag when
84 constructing the event_config, or set the EVENT_PRECISE_TIMER
85 environment variable to a non-empty string.
87 There is an EVLOOP_NO_EXIT_ON_EMPTY flag that tells event_base_loop()
88 to keep looping even when there are no pending events. (Ordinarily,
89 event_base_loop() will exit as soon as no events are pending.)
91 Past versions of Libevent have been annoying to use with some
92 memory-leak-checking tools, because Libevent allocated some global
93 singletons but provided no means to free them. There is now a
94 function, libevent_global_shutdown(), that you can use to free all
95 globally held resources before exiting, so that your leak-check tools
96 don't complain. (Note: this function doesn't free non-global things
97 like events, bufferevents, and so on; and it doesn't free anything
98 that wouldn't otherwise get cleaned up by the operating system when
99 your process exit()s. If you aren't using a leak-checking tool, there
100 is not much reason to call libevent_global_shutdown().)
102 There is a new event_base_get_npriorities() function to return the
103 number of priorities set in the event base.
105 Libevent 2.0 added an event_new() function to construct a new struct
106 event on the heap. Unfortunately, with event_new(), there was no
110 event_assign(&ev, base, fd, EV_READ, callback, &ev);
112 In other words, there was no easy way for event_new() to set up an
113 event so that the event itself would be its callback argument.
114 Libevent 2.1 lets you do this by passing "event_self_cbarg()" as the
118 evp = event_new(base, fd, EV_READ, callback,
121 There's also a new event_base_get_running_event() function you can
122 call from within a Libevent callback to get a pointer to the current
123 event. This should never be strictly necessary, but it's sometimes
126 The event_base_once() function used to leak some memory if the event
127 that it added was never actually triggered. Now, its memory is
128 tracked in the event_base and freed when the event_base is freed.
129 Note however that Libevent doesn't know how to free any information
130 passed as the callback argument to event_base_once is still something
131 you'll might need a way to de-allocate yourself.
133 There is an event_get_priority() function to return an event's
136 By analogy to event_base_loopbreak(), there is now an
137 event_base_loopcontinue() that tells Libevent to stop processing
138 active event callbacks, and re-scan for new events right away.
140 There's a function, event_base_foreach_event(), that can iterate over
141 every event currently pending or active on an event base, and invoke a
142 user-supplied callback on each. The callback must not alter the events
143 or add or remove anything to the event base.
145 We now have an event_remove_timer() function to remove the timeout on
146 an event while leaving its socket and/or signal triggers unchanged.
147 (If we were designing the API from scratch, this would be the behavior
148 of "event_add(ev, NULL)" on an already-added event with a timeout. But
149 that's a no-op in past versions of Libevent, and we don't want to
150 break compatibility.)
152 You can use the new event_base_get_num_events() function to find the
153 number of events active or pending on an event_base. To find the
154 largest number of events that there have been since the last call, use
155 event_base_get_max_events().
157 You can now activate all the events waiting for a given fd or signal
158 using the event_base_active_by_fd() and event_base_active_by_signal()
161 On backends that support it (currently epoll), there is now an
162 EV_CLOSED flag that programs can use to detect when a socket has
163 closed without having to read all the bytes until receiving an EOF.
165 1.3. Event finalization
167 [NOTE: This is an experimental feature in Libevent 2.1.3-alpha. Though
168 it seems solid so far, its API might change between now and the first
169 release candidate for Libevent 2.1.]
171 1.3.1. Why event finalization?
173 Libevent 2.1 now supports an API for safely "finalizing" events that
174 might be running in multiple threads, and provides a way to slightly
175 change the semantics of event_del() to prevent deadlocks in
176 multithreaded programs.
178 To motivate this feature, consider the following code, in the context
179 of a mulithreaded Libevent application:
181 struct connection *conn = event_get_callback_arg(ev);
183 connection_free(conn);
185 Suppose that the event's callback might be running in another thread,
186 and using the value of "conn" concurrently. We wouldn't want to
187 execute the connection_free() call until "conn" is no longer in use.
188 How can we make this code safe?
190 Libevent 2.0 answered that question by saying that the event_del()
191 call should block if the event's callback is running in another
192 thread. That way, we can be sure that event_del() has canceled the
193 callback (if the callback hadn't started running yet), or has waited
194 for the callback to finish.
196 But now suppose that the data structure is protected by a lock, and we
197 have the following code:
199 void check_disable(struct connection *connection) {
201 if (should_stop_reading(connection))
202 event_del(connection->read_event);
206 What happens when we call check_disable() from a callback and from
207 another thread? Let's say that the other thread gets the lock
208 first. If it decides to call event_del(), it will wait for the
209 callback to finish. But meanwhile, the callback will be waiting for
210 the lock on the connection. Since each threads is waiting for the
211 other one to release a resource, the program will deadlock.
213 This bug showed up in multithreaded bufferevent programs in 2.1,
214 particularly when freeing bufferevents. (For more information, see
215 the "Deadlock when calling bufferevent_free from an other thread"
216 thread on libevent-users starting on 6 August 2012 and running through
217 February of 2013. You might also like to read my earlier writeup at
218 http://archives.seul.org/libevent/users/Feb-2012/msg00053.html and
219 the ensuing discussion.)
221 1.3.2. The EV_FINALIZE flag and avoiding deadlock
223 To prevent the deadlock condition described above, Libevent
224 2.1.3-alpha adds a new flag, "EV_FINALIZE". You can pass it to
225 event_new() and event_assign() along with EV_READ, EV_WRITE, and the
228 When an event is constructed with the EV_FINALIZE flag, event_del()
229 will not block on that event, even when the event's callback is
230 running in another thread. By using EV_FINALIZE, you are therefore
231 promising not to use the "event_del(ev); free(event_get_callback_arg(ev));"
232 pattern, but rather to use one of the finalization functions below to
235 EV_FINALIZE has no effect on a single-threaded program, or on a
236 program where events are only used from one thread.
239 There are also two new variants of event_del() that you can use for
240 more fine-grained control:
241 event_del_noblock(ev)
243 The event_del_noblock() function will never block, even if the event
244 callback is running in another thread and doesn't have the EV_FINALIZE
245 flag. The event_del_block() function will _always_ block if the event
246 callback is running in another thread, even if the event _does_ have
247 the EV_FINALIZE flag.
249 [A future version of Libevent may have a way to make the EV_FINALIZE
252 1.3.3. Safely finalizing events
254 To safely tear down an event that may be running, Libevent 2.1.3-alpha
255 introduces event_finalize() and event_free_finalize(). You call them
256 on an event, and provide a finalizer callback to be run on the event
257 and its callback argument once the event is definitely no longer
260 With event_free_finalize(), the event is also freed once the finalizer
261 callback has been invoked.
263 A finalized event cannot be re-added or activated. The finalizer
264 callback must not add events, activate events, or attempt to
265 "resucitate" the event being finalized in any way.
267 If any finalizer callbacks are pending as the event_base is being
268 freed, they will be invoked. You can override this behavior with the
269 new function event_base_free_nofinalize().
271 1.4. New debugging features
273 You can now turn on debug logs at runtime using a new function,
274 event_enable_debug_logging().
276 The event_enable_lock_debugging() function is now spelled correctly.
277 You can still use the old "event_enable_lock_debuging" name, though,
278 so your old programs shouldnt' break.
280 There's also been some work done to try to make the debugging logs
281 more generally useful.
283 1.5. New evbuffer functions
285 In Libevent 2.0, we introduced evbuffer_add_file() to add an entire
286 file's contents to an evbuffer, and then send them using sendfile() or
287 mmap() as appropriate. This API had some drawbacks, however.
288 Notably, it created one mapping or fd for every instance of the same
289 file added to any evbuffer. Also, adding a file to an evbuffer could
290 make that buffer unusable with SSL bufferevents, filtering
291 bufferevents, and any code that tried to read the contents of the
294 Libevent 2.1 adds a new evbuffer_file_segment API to solve these
295 problems. Now, you can use evbuffer_file_segment_new() to construct a
296 file-segment object, and evbuffer_add_file_segment() to insert it (or
297 part of it) into an evbuffer. These segments avoid creating redundant
298 maps or fds. Better still, the code is smart enough (when the OS
299 supports sendfile) to map the file when that's necessary, and use
300 sendfile() otherwise.
302 File segments can receive callback functions that are invoked when the
303 file segments are freed.
305 The evbuffer_ptr interface has been extended so that an evbuffer_ptr
306 can now yield a point just after the end of the buffer. This makes
307 many algorithms simpler to implement.
309 There's a new evbuffer_add_buffer() interface that you can use to add
310 one buffer to another nondestructively. When you say
311 evbuffer_add_buffer_reference(outbuf, inbuf), outbuf now contains a
312 reference to the contents of inbuf.
314 To aid in adding data in bulk while minimizing evbuffer calls, there
315 is an evbuffer_add_iovec() function.
317 There's a new evbuffer_copyout_from() variant function to enable
318 copying data nondestructively from the middle of a buffer.
320 evbuffer_readln() now supports an EVBUFFER_EOL_NUL argument to fetch
321 NUL-terminated strings from buffers.
323 1.6. New functions and features: bufferevents
325 You can now use the bufferevent_getcb() function to find out a
326 bufferevent's callbacks. Previously, there was no supported way to do
329 The largest chunk readable or writeable in a single bufferevent
330 callback is no longer hardcoded; it's now configurable with
331 the new functions bufferevent_set_max_single_read() and
332 bufferevent_set_max_single_write().
334 For consistency, OpenSSL bufferevents now make sure to always set one
335 of BEV_EVENT_READING or BEV_EVENT_WRITING when invoking an event
338 Calling bufferevent_set_timeouts(bev, NULL, NULL) now removes the
339 timeouts from socket and ssl bufferevents correctly.
341 You can find the priority at which a bufferevent runs with
342 bufferevent_get_priority().
344 The function bufferevent_get_token_bucket_cfg() can retrieve the
345 rate-limit settings for a bufferevent; bufferevent_getwatermark() can
346 return a bufferevent's current watermark settings.
348 You can manually trigger a bufferevent's callbacks via
349 bufferevent_trigger() and bufferevent_trigger_event().
351 1.7. New functions and features: evdns
353 The previous evdns interface used an "open a test UDP socket" trick in
354 order to detect IPv6 support. This was a hack, since it would
355 sometimes badly confuse people's firewall software, even though no
356 packets were sent. The current evdns interface-detection code uses
357 the appropriate OS functions to see which interfaces are configured.
359 The evdns_base_new() function now has multiple possible values for its
360 second (flags) argument. Using 1 and 0 have their old meanings, though the
361 1 flag now has a symbolic name of EVDNS_BASE_INITIALIZE_NAMESERVERS.
362 A second flag is now supported too: the EVDNS_BASE_DISABLE_WHEN_INACTIVE
363 flag, which tells the evdns_base that it should not prevent Libevent from
364 exiting while it has no DNS requests in progress.
366 There is a new evdns_base_clear_host_addresses() function to remove
367 all the /etc/hosts addresses registered with an evdns instance.
369 1.8. New functions and features: evconnlistener
371 Libevent 2.1 adds the following evconnlistener flags:
373 LEV_OPT_DEFERRED_ACCEPT -- Tells the OS that it doesn't need to
374 report sockets as having arrived until the initiator has sent some
375 data too. This can greatly improve performance with protocols like
376 HTTP where the client always speaks first. On operating systems
377 that don't support this functionality, this option has no effect.
379 LEV_OPT_DISABLED -- Creates an evconnlistener in the disabled (not
382 Libevent 2.1 changes the behavior of the LEV_OPT_CLOSE_ON_EXEC
383 flag. Previously, it would apply to the listener sockets, but not to
384 the accepted sockets themselves. That's almost never what you want.
385 Now, it applies both to the listener and the accepted sockets.
387 1.9. New functions and features: evhttp
389 **********************************************************************
390 NOTE: The evhttp module will eventually be deprecated in favor of Mark
391 Ellzey's libevhtp library. Don't worry -- this won't happen until
392 libevhtp provides every feature that evhttp does, and provides a
393 compatible interface that applications can use to migrate.
394 **********************************************************************
396 Previously, you could only set evhttp timeouts in increments of one
397 second. Now, you can use evhttp_set_timeout_tv() and
398 evhttp_connection_set_timeout_tv() to configure
399 microsecond-granularity timeouts.
401 There are a new pair of functions: evhttp_set_bevcb() and
402 evhttp_connection_base_bufferevent_new(), that you can use to
403 configure which bufferevents will be used for incoming and outgoing
404 http connections respectively. These functions, combined with SSL
405 bufferevents, should enable HTTPS support.
407 There's a new evhttp_foreach_bound_socket() function to iterate over
408 every listener on an evhttp object.
410 Whitespace between lines in headers is now folded into a single space;
411 whitespace at the end of a header is now removed.
413 The socket errno value is now preserved when invoking an http error
416 There's a new kind of request callback for errors; you can set it with
417 evhttp_request_set_error_cb(). It gets called when there's a request error,
418 and actually reports the error code and lets you figure out which request
421 You can navigate from an evhttp_connection back to its evhttp with the
422 new evhttp_connection_get_server() function.
424 You can override the default HTTP Content-Type with the new
425 evhttp_set_default_content_type() function
427 There's a new evhttp_connection_get_addr() API to return the peer
428 address of an evhttp_connection.
430 The new evhttp_send_reply_chunk_with_cb() is a variant of
431 evhttp_send_reply_chunk() with a callback to be invoked when the
434 The evhttp_request_set_header_cb() facility adds a callback to be
435 invoked while parsing headers.
437 The evhttp_request_set_on_complete_cb() facility adds a callback to be
438 invoked on request completion.
440 1.10. New functions and features: evutil
442 There's a function "evutil_secure_rng_set_urandom_device_file()" that
443 you can use to override the default file that Libevent uses to seed
444 its (sort-of) secure RNG.
446 2. Cross-platform performance improvements
448 2.1. Better data structures
450 We replaced several users of the sys/queue.h "TAILQ" data structure
451 with the "LIST" data structure. Because this data type doesn't
452 require FIFO access, it requires fewer pointer checks and
453 manipulations to keep it in line.
455 All previous versions of Libevent have kept every pending (added)
456 event in an "eventqueue" data structure. Starting in Libevent 2.0,
457 however, this structure became redundant: every pending timeout event
458 is stored in the timeout heap or in one of the common_timeout queues,
459 and every pending fd or signal event is stored in an evmap. Libevent
460 2.1 removes this data structure, and thereby saves all of the code
461 that we'd been using to keep it updated.
463 2.2. Faster activations and timeouts
465 It's a common pattern in older code to use event_base_once() with a
466 0-second timeout to ensure that a callback will get run 'as soon as
467 possible' in the current iteration of the Libevent loop. We optimize
468 this case by calling event_active() directly, and bypassing the
469 timeout pool. (People who are using this pattern should also consider
470 using event_active() themselves.)
472 Libevent 2.0 would wake up a polling event loop whenever the first
473 timeout in the event loop was adjusted--whether it had become earlier
474 or later. We now only notify the event loop when a change causes the
475 expiration time to become _sooner_ than it would have been otherwise.
477 The timeout heap code is now optimized to perform fewer comparisons
478 and shifts when changing or removing a timeout.
480 Instead of checking for a wall-clock time jump every time we call
481 clock_gettime(), we now check only every 5 seconds. This should save
482 a huge number of gettimeofday() calls.
484 2.3. Microoptimizations
486 Internal event list maintainance no longer use the antipattern where
487 we have one function with multiple totally independent behaviors
488 depending on an argument:
492 void func(int operation, struct event *ev) {
497 Instead, these functions are now split into separate functions for
499 void func_op1(struct event *ev) { ... }
500 void func_op2(struct event *ev) { ... }
501 void func_op3(struct event *ev) { ... }
503 This produces better code generation and inlining decisions on some
504 compilers, and makes the code easier to read and check.
506 2.4. Evbuffer performance improvements
508 The EVBUFFER_EOL_CRLF line-ending type is now much faster, thanks to
511 2.5. HTTP performance improvements
513 o Performance tweak to evhttp_parse_request_line. (aee1a97 Mark Ellzey)
514 o Add missing break to evhttp_parse_request_line (0fcc536)
516 2.6. Coarse timers by default on Linux
518 Due to limitations of the epoll interface, Libevent programs using epoll
519 have not previously been able to wait for timeouts with accuracy smaller
520 than 1 millisecond. But Libevent had been using CLOCK_MONOTONIC for
521 timekeeping on Linux, which is needlessly expensive: CLOCK_MONOTONIC_COARSE
522 has approximately the resolution corresponding to epoll, and is much faster
523 to invoke than CLOCK_MONOTONIC.
525 To disable coarse timers, and get a more plausible precision, use the
526 new EVENT_BASE_FLAG_PRECISE_TIMER flag when setting up your event base.
528 3. Backend/OS-specific improvements
530 3.1. Linux-specific improvements
532 The logic for deciding which arguements to use with epoll_ctl() is now
533 a table-driven lookup, rather than the previous pile of cascading
534 branches. This should minimize epoll_ctl() calls and make the epoll
535 code run a little faster on change-heavy loads.
537 Libevent now takes advantage of Linux's support for enhanced APIs
538 (e.g., SOCK_CLOEXEC, SOCK_NONBLOCK, accept4, pipe2) that allow us to
539 simultaneously create a socket, make it nonblocking, and make it
540 close-on-exec. This should save syscalls throughout our codebase, and
541 avoid race-conditions if an exec() occurs after a socket is socket is
542 created but before we can make it close-on-execute on it.
544 3.2. Windows-specific improvements
546 We now use GetSystemTimeAsFileTime to implement gettimeofday. It's
547 significantly faster and more accurate than our old ftime()-based approach.
549 3.3. Improvements in the solaris evport backend.
551 The evport backend has been updated to use many of the infrastructure
552 improvements from Libevent 2.0. Notably, it keeps track of per-fd
553 information using the evmap infrastructure, and removes a number of
554 linear scans over recently-added events. This last change makes it
555 efficient to receive many more events per evport_getn() call, thereby
556 reducing evport overhead in general.
558 3.4. OSX backend improvements
560 The OSX select backend doesn't like to have more than a certain number
561 of fds set unless an "unlimited select" option has been set.
562 Therefore, we now set it.
564 3.5. Monotonic clocks on even more platforms
566 Libevent previously used a monotonic clock for its internal timekeeping
567 only on platforms supporting the POSIX clock_gettime() interface. Now,
568 Libevent has support for monotonic clocks on OSX and Windows too, and a
569 fallback implementation for systems without monotonic clocks that will at
570 least keep time running forwards.
572 Using monotonic timers makes Libevent more resilient to changes in the
573 system time, as can happen in small amounts due to clock adjustments from
574 NTP, or in large amounts due to users who move their system clocks all over
575 the timeline in order to keep nagware from nagging them.
577 3.6. Faster cross-thread notification on kqueue
579 When a thread other than the one in which the main event loop is
580 running needs to wake the thread running the main event loop, Libevent
581 usually writes to a socketpair in order to force the main event loop
582 to wake up. On Linux, we've been able to use eventfd() instead. Now
583 on BSD and OSX systems (any anywhere else that has kqueue with the
584 EVFILT_USER extension), we can use EVFILT_USER to wake up the main
585 thread from kqueue. This should be a tiny bit faster than the
588 4. Infrastructure improvements
592 I've spent some time to try to make the unit tests run faster in
593 Libevent 2.1. Nearly all of this was a matter of searching slow tests
594 for unreasonably long timeouts, and cutting them down to reasonably
595 long delays, though on one or two cases I actually had to parallelize
596 an operation or improve an algorithm.
598 On my desktop, a full "make verify" run of Libevent 2.0.18-stable
599 requires about 218 seconds. Libevent 2.1.1-alpha cuts this down to
602 Faster unit tests are great, since they let programmers test their
603 changes without losing their train of thought.
605 4.2. Finicky tests are now off-by-default
607 The Tinytest unit testing framework now supports optional tests, and
608 Libevent uses them. By default, Libevent's unit testing framework
609 does not run tests that require a working network, and does not run
610 tests that tend to fail on heavily loaded systems because of timing
611 issues. To re-enable all tests, run ./test/regress using the "@all"
614 4.3. Modernized use of autotools
616 Our autotools-based build system has been updated to build without
617 warnings on recent autoconf/automake versions.
619 Libevent's autotools makefiles are no longer recursive. This allows
620 make to use the maximum possible parallelism to do the minimally
621 necessary amount of work. See Peter Miller's "Recursive Make
622 Considered Harmful" at http://miller.emu.id.au/pmiller/books/rmch/ for
623 more information here.
625 We now use the "quiet build" option to suppress distracting messages
626 about which commandlines are running. You can get them back with
631 Libevent now uses large-file support internally on platforms where it
632 matters. You shouldn't need to set _LARGEFILE or OFFSET_BITS or
633 anything magic before including the Libevent headers, either, since
634 Libevent now sets the size of ev_off_t to the size of off_t that it
635 received at compile time, not to some (possibly different) size based
636 on current macro definitions when your program is building.
638 We now also use the Autoconf AC_USE_SYSTEM_EXTENSIONS mechanism to
639 enable per-system macros needed to enable not-on-by-default features.
640 Unlike the rest of the autoconf macros, we output these to an
641 internal-use-only evconfig-private.h header, since their names need to
642 survive unmangled. This lets us build correctly on more platforms,
643 and avoid inconsistencies when some files define _GNU_SOURCE and
646 Libevent now tries to detect OpenSSL via pkg-config.
648 4.5. Standards conformance
650 Previous Libevent versions had no consistent convention for internal
651 vs external identifiers, and used identifiers starting with the "_"
652 character throughout the codebase. That's no good, since the C
653 standard says that identifiers beginning with _ are reserved. I'm not
654 aware of having any collisions with system identifiers, but it's best
655 to fix these things before they cause trouble.
657 We now avoid all use of the _identifiers in the Libevent source code.
658 These changes were made *mainly* through the use of automated scripts,
659 so there shouldn't be any mistakes, but you never know.
661 As an exception, the names _EVENT_LOG_DEBUG, _EVENT_LOG_MSG_,
662 _EVENT_LOG_WARN, and _EVENT_LOG_ERR are still exposed in event.h: they
663 are now deprecated, but to support older code, they will need to stay
664 around for a while. New code should use EVENT_LOG_DEBUG,
665 EVENT_LOG_MSG, EVENT_LOG_WARN, and EVENT_LOG_ERR instead.
667 4.6. Event and callback refactoring
669 As a simplification and optimization to Libevent's "deferred callback"
670 logic (introduced in 2.0 to avoid callback recursion), Libevent now
671 treats all of its deferrable callback types using the same logic it
672 uses for active events. Now deferred events no longer cause priority
673 inversion, no longer require special code to cancel them, and so on.
675 Regular events and deferred callbacks now both descend from an
676 internal light-weight event_callback supertype, and both support
677 priorities and take part in the other anti-priority-inversion
678 mechanisms in Libevent.
680 To avoid starvation from callback recursion (which was the reason we
681 introduced "deferred callbacks" in the first place) the implementation
682 now allows an event callback to be scheduled as "active later":
683 instead of running in the current iteration of the event loop, it runs
688 Libevent's test coverage level is more or less unchanged since before:
689 we still have over 80% line coverage in our tests on Linux and OSX.
690 There are some under-tested modules, though: we need to fix those.