1 What's new in Libevent 2.1 2 Nick Mathewson 3 40. Before we start 5 60.1. About this document 7 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. 10 11 For better documentation about libevent, see the links at 12 http://libevent.org/ 13 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! 17 18 NOTE: I am very sure that I missed some thing on this list. Caveat 19 haxxor. 20 210.2. Where to get help 22 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. 26 27 There is a work-in-progress book with reference manual at 28 http://www.wangafu.net/~nickm/libevent-book/ . 29 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. 33 340.3. Compatibility 35 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. 41 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.3-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. 47 481. New APIs and features 49 501.1. New ways to build libevent 51 52 We now provide an --enable-gcc-hardening configure option to turn on 53 GCC features designed for increased code security. 54 55 There is also an --enable-silent-rules configure option to make 56 compilation run more quietly with automake 1.11 or later. 57 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. 61 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 64 upset. 65 66 671.2. New functions for events and the event loop 68 69 If you're running Libevent with multiple event priorities, you might 70 want to make sure that Libevent checks for new events frequently, so 71 that time-consuming or numerous low-priority events don't keep it from 72 checking for new high-priority events. You can now use the 73 event_config_set_max_dispatch_interval() interface to ensure that the 74 loop checks for new events either every N microseconds, every M 75 callbacks, or both. 76 77 When configuring an event base, you can now choose whether you want 78 timers to be more efficient, or more precise. (This only has effect 79 on Linux for now.) Timers are efficient by default: to select more 80 precise timers, use the EVENT_BASE_FLAG_PRECISE_TIMER flag when 81 constructing the event_config, or set the EVENT_PRECISE_TIMER 82 environment variable to a non-empty string. 83 84 There is an EVLOOP_NO_EXIT_ON_EMPTY flag that tells event_base_loop() 85 to keep looping even when there are no pending events. (Ordinarily, 86 event_base_loop() will exit as soon as no events are pending.) 87 88 Past versions of Libevent have been annoying to use with some 89 memory-leak-checking tools, because Libevent allocated some global 90 singletons but provided no means to free them. There is now a 91 function, libevent_global_shutdown(), that you can use to free all 92 globally held resources before exiting, so that your leak-check tools 93 don't complain. (Note: this function doesn't free non-global things 94 like events, bufferevents, and so on; and it doesn't free anything 95 that wouldn't otherwise get cleaned up by the operating system when 96 your process exit()s. If you aren't using a leak-checking tool, there 97 is not much reason to call libevent_global_shutdown().) 98 99 There is a new event_base_get_npriorities() function to return the 100 number of priorities set in the event base. 101 102 Libevent 2.0 added an event_new() function to construct a new struct 103 event on the heap. Unfortunately, with event_new(), there was no 104 equivalent for: 105 106 struct event ev; 107 event_assign(&ev, base, fd, EV_READ, callback, &ev); 108 109 In other words, there was no easy way for event_new() to set up an 110 event so that the event itself would be its callback argument. 111 Libevent 2.1 lets you do this by passing "event_self_cbarg()" as the 112 callback argument: 113 114 struct event *evp; 115 evp = event_new(base, fd, EV_READ, callback, 116 event_self_cbarg()); 117 118 There's also a new event_base_get_running_event() function you can 119 call from within a Libevent callback to get a pointer to the current 120 event. This should never be strictly necessary, but it's sometimes 121 convenient. 122 123 The event_base_once() function used to leak some memory if the event 124 that it added was never actually triggered. Now, its memory is 125 tracked in the event_base and freed when the event_base is freed. 126 Note however that Libevent doesn't know how to free any information 127 passed as the callback argument to event_base_once is still something 128 you'll might need a way to de-allocate yourself. 129 130 There is an event_get_priority() function to return an event's 131 priority. 132 133 By analogy to event_base_loopbreak(), there is now an 134 event_base_loopcontinue() that tells Libevent to stop processing 135 active event callbacks, and re-scan for new events right away. 136 137 There's a function, event_base_foreach_event(), that can iterate over 138 every event currently pending or active on an event base, and invoke a 139 user-supplied callback on each. The callback must not alter the events 140 or add or remove anything to the event base. 141 142 We now have an event_remove_timer() function to remove the timeout on 143 an event while leaving its socket and/or signal triggers unchanged. 144 (If we were designing the API from scratch, this would be the behavior 145 of "event_add(ev, NULL)" on an already-added event with a timeout. But 146 that's a no-op in past versions of Libevent, and we don't want to 147 break compatibility.) 148 1491.3. Event finalization 150 151 [NOTE: This is an experimental feature in Libevent 2.1.3-alpha. Though 152 it seems solid so far, its API might change between now and the first 153 release candidate for Libevent 2.1.] 154 1551.3.1. Why event finalization? 156 157 Libevent 2.1 now supports an API for safely "finalizing" events that 158 might be running in multiple threads, and provides a way to slightly 159 change the semantics of event_del() to prevent deadlocks in 160 multithreaded programs. 161 162 To motivate this feature, consider the following code, in the context 163 of a mulithreaded Libevent application: 164 165 struct connection *conn = event_get_callback_arg(ev); 166 event_del(ev); 167 connection_free(conn); 168 169 Suppose that the event's callback might be running in another thread, 170 and using the value of "conn" concurrently. We wouldn't want to 171 execute the connection_free() call until "conn" is no longer in use. 172 How can we make this code safe? 173 174 Libevent 2.0 answered that question by saying that the event_del() 175 call should block if the event's callback is running in another 176 thread. That way, we can be sure that event_del() has canceled the 177 callback (if the callback hadn't started running yet), or has waited 178 for the callback to finish. 179 180 But now suppose that the data structure is protected by a lock, and we 181 have the following code: 182 183 void check_disable(struct connection *connection) { 184 lock(connection); 185 if (should_stop_reading(connection)) 186 event_del(connection->read_event); 187 unlock(connection); 188 } 189 190 What happens when we call check_disable() from a callback and from 191 another thread? Let's say that the other thread gets the lock 192 first. If it decides to call event_del(), it will wait for the 193 callback to finish. But meanwhile, the callback will be waiting for 194 the lock on the connection. Since each threads is waiting for the 195 other one to release a resource, the program will deadlock. 196 197 This bug showed up in multithreaded bufferevent programs in 2.1, 198 particularly when freeing bufferevents. (For more information, see 199 the "Deadlock when calling bufferevent_free from an other thread" 200 thread on libevent-users starting on 6 August 2012 and running through 201 February of 2013. You might also like to read my earlier writeup at 202 http://archives.seul.org/libevent/users/Feb-2012/msg00053.html and 203 the ensuing discussion.) 204 2051.3.2. The EV_FINALIZE flag and avoiding deadlock 206 207 To prevent the deadlock condition described above, Libevent 208 2.1.3-alpha adds a new flag, "EV_FINALIZE". You can pass it to 209 event_new() and event_assign() along with EV_READ, EV_WRITE, and the 210 other event flags. 211 212 When an event is constructed with the EV_FINALIZE flag, event_del() 213 will not block on that event, even when the event's callback is 214 running in another thread. By using EV_FINALIZE, you are therefore 215 promising not to use the "event_del(ev); free(event_get_callback_arg(ev));" 216 pattern, but rather to use one of the finalization functions below to 217 clean up the event. 218 219 EV_FINALIZE has no effect on a single-threaded program, or on a 220 program where events are only used from one thread. 221 222 223 There are also two new variants of event_del() that you can use for 224 more fine-grained control: 225 event_del_noblock(ev) 226 event_del_block(ev) 227 The event_del_noblock() function will never block, even if the event 228 callback is running in another thread and doesn't have the EV_FINALIZE 229 flag. The event_del_block() function will _always_ block if the event 230 callback is running in another thread, even if the event _does_ have 231 the EV_FINALIZE flag. 232 233 [A future version of Libevent may have a way to make the EV_FINALIZE 234 flag the default.] 235 2361.3.3. Safely finalizing events 237 238 To safely tear down an event that may be running, Libevent 2.1.3-alpha 239 introduces event_finalize() and event_free_finalize(). You call them 240 on an event, and provide a finalizer callback to be run on the event 241 and its callback argument once the event is definitely no longer 242 running. 243 244 With event_free_finalize(), the event is also freed once the finalizer 245 callback has been invoked. 246 247 A finalized event cannot be re-added or activated. The finalizer 248 callback must not add events, activate events, or attempt to 249 "resucitate" the event being finalized in any way. 250 251 If any finalizer callbacks are pending as the event_base is being 252 freed, they will be invoked. You can override this behavior with the 253 new function event_base_free_nofinalize(). 254 2551.4. New debugging features 256 257 You can now turn on debug logs at runtime using a new function, 258 event_enable_debug_logging(). 259 260 The event_enable_lock_debugging() function is now spelled correctly. 261 You can still use the old "event_enable_lock_debuging" name, though, 262 so your old programs shouldnt' break. 263 264 There's also been some work done to try to make the debugging logs 265 more generally useful. 266 2671.5. New evbuffer functions 268 269 In Libevent 2.0, we introduced evbuffer_add_file() to add an entire 270 file's contents to an evbuffer, and then send them using sendfile() or 271 mmap() as appropriate. This API had some drawbacks, however. 272 Notably, it created one mapping or fd for every instance of the same 273 file added to any evbuffer. Also, adding a file to an evbuffer could 274 make that buffer unusable with SSL bufferevents, filtering 275 bufferevents, and any code that tried to read the contents of the 276 evbuffer. 277 278 Libevent 2.1 adds a new evbuffer_file_segment API to solve these 279 problems. Now, you can use evbuffer_file_segment_new() to construct a 280 file-segment object, and evbuffer_add_file_segment() to insert it (or 281 part of it) into an evbuffer. These segments avoid creating redundant 282 maps or fds. Better still, the code is smart enough (when the OS 283 supports sendfile) to map the file when that's necessary, and use 284 sendfile() otherwise. 285 286 File segments can receive callback functions that are invoked when the 287 file segments are freed. 288 289 The evbuffer_ptr interface has been extended so that an evbuffer_ptr 290 can now yield a point just after the end of the buffer. This makes 291 many algorithms simpler to implement. 292 293 There's a new evbuffer_add_buffer() interface that you can use to add 294 one buffer to another nondestructively. When you say 295 evbuffer_add_buffer_reference(outbuf, inbuf), outbuf now contains a 296 reference to the contents of inbuf. 297 298 To aid in adding data in bulk while minimizing evbuffer calls, there 299 is an evbuffer_add_iovec() function. 300 301 There's a new evbuffer_copyout_from() variant function to enable 302 copying data nondestructively from the middle of a buffer. 303 304 evbuffer_readln() now supports an EVBUFFER_EOL_NUL argument to fetch 305 NUL-terminated strings from buffers. 306 3071.6. New functions and features: bufferevents 308 309 You can now use the bufferevent_getcb() function to find out a 310 bufferevent's callbacks. Previously, there was no supported way to do 311 that. 312 313 The largest chunk readable or writeable in a single bufferevent 314 callback is no longer hardcoded; it's now configurable with 315 the new functions bufferevent_set_max_single_read() and 316 bufferevent_set_max_single_write(). 317 318 For consistency, OpenSSL bufferevents now make sure to always set one 319 of BEV_EVENT_READING or BEV_EVENT_WRITING when invoking an event 320 callback. 321 322 Calling bufferevent_set_timeouts(bev, NULL, NULL) now removes the 323 timeouts from socket and ssl bufferevents correctly. 324 325 You can find the priority at which a bufferevent runs with 326 bufferevent_get_priority(). 327 3281.7. New functions and features: evdns 329 330 The previous evdns interface used an "open a test UDP socket" trick in 331 order to detect IPv6 support. This was a hack, since it would 332 sometimes badly confuse people's firewall software, even though no 333 packets were sent. The current evdns interface-detection code uses 334 the appropriate OS functions to see which interfaces are configured. 335 336 The evdns_base_new() function now has multiple possible values for its 337 second (flags) argument. Using 1 and 0 have their old meanings, though the 338 1 flag now has a symbolic name of EVDNS_BASE_INITIALIZE_NAMESERVERS. 339 A second flag is now supported too: the EVDNS_BASE_DISABLE_WHEN_INACTIVE 340 flag, which tells the evdns_base that it should not prevent Libevent from 341 exiting while it has no DNS requests in progress. 342 3431.8. New functions and features: evconnlistener 344 345 Libevent 2.1 adds the following evconnlistener flags: 346 347 LEV_OPT_DEFERRED_ACCEPT -- Tells the OS that it doesn't need to 348 report sockets as having arrived until the initiator has sent some 349 data too. This can greatly improve performance with protocols like 350 HTTP where the client always speaks first. On operating systems 351 that don't support this functionality, this option has no effect. 352 353 LEV_OPT_DISABLED -- Creates an evconnlistener in the disabled (not 354 listening) state. 355 356 Libevent 2.1 changes the behavior of the LEV_OPT_CLOSE_ON_EXEC 357 flag. Previously, it would apply to the listener sockets, but not to 358 the accepted sockets themselves. That's almost never what you want. 359 Now, it applies both to the listener and the accepted sockets. 360 3611.9. New functions and features: evhttp 362 363 ********************************************************************** 364 NOTE: The evhttp module will eventually be deprecated in favor of Mark 365 Ellzey's libevhtp library. Don't worry -- this won't happen until 366 libevhtp provides every feature that evhttp does, and provides a 367 compatible interface that applications can use to migrate. 368 ********************************************************************** 369 370 Previously, you could only set evhttp timeouts in increments of one 371 second. Now, you can use evhttp_set_timeout_tv() and 372 evhttp_connection_set_timeout_tv() to configure 373 microsecond-granularity timeouts. 374 375 There are a new pair of functions: evhttp_set_bevcb() and 376 evhttp_connection_base_bufferevent_new(), that you can use to 377 configure which bufferevents will be used for incoming and outgoing 378 http connections respectively. These functions, combined with SSL 379 bufferevents, should enable HTTPS support. 380 381 There's a new evhttp_foreach_bound_socket() function to iterate over 382 every listener on an evhttp object. 383 384 Whitespace between lines in headers is now folded into a single space; 385 whitespace at the end of a header is now removed. 386 387 The socket errno value is now preserved when invoking an http error 388 callback. 389 390 There's a new kind of request callback for errors; you can set it with 391 evhttp_request_set_error_cb(). It gets called when there's a request error, 392 and actually reports the error code and lets you figure out which request 393 failed. 394 3952. Cross-platform performance improvements 396 3972.1. Better data structures 398 399 We replaced several users of the sys/queue.h "TAILQ" data structure 400 with the "LIST" data structure. Because this data type doesn't 401 require FIFO access, it requires fewer pointer checks and 402 manipulations to keep it in line. 403 404 All previous versions of Libevent have kept every pending (added) 405 event in an "eventqueue" data structure. Starting in Libevent 2.0, 406 however, this structure became redundant: every pending timeout event 407 is stored in the timeout heap or in one of the common_timeout queues, 408 and every pending fd or signal event is stored in an evmap. Libevent 409 2.1 removes this data structure, and thereby saves all of the code 410 that we'd been using to keep it updated. 411 4122.2. Faster activations and timeouts 413 414 It's a common pattern in older code to use event_base_once() with a 415 0-second timeout to ensure that a callback will get run 'as soon as 416 possible' in the current iteration of the Libevent loop. We optimize 417 this case by calling event_active() directly, and bypassing the 418 timeout pool. (People who are using this pattern should also consider 419 using event_active() themselves.) 420 421 Libevent 2.0 would wake up a polling event loop whenever the first 422 timeout in the event loop was adjusted--whether it had become earlier 423 or later. We now only notify the event loop when a change causes the 424 expiration time to become _sooner_ than it would have been otherwise. 425 426 The timeout heap code is now optimized to perform fewer comparisons 427 and shifts when changing or removing a timeout. 428 429 Instead of checking for a wall-clock time jump every time we call 430 clock_gettime(), we now check only every 5 seconds. This should save 431 a huge number of gettimeofday() calls. 432 4332.3. Microoptimizations 434 435 Internal event list maintainance no longer use the antipattern where 436 we have one function with multiple totally independent behaviors 437 depending on an argument: 438 #define OP1 1 439 #define OP2 2 440 #define OP3 3 441 void func(int operation, struct event *ev) { 442 switch (op) { 443 ... 444 } 445 } 446 Instead, these functions are now split into separate functions for 447 each operation: 448 void func_op1(struct event *ev) { ... } 449 void func_op2(struct event *ev) { ... } 450 void func_op3(struct event *ev) { ... } 451 452 This produces better code generation and inlining decisions on some 453 compilers, and makes the code easier to read and check. 454 4552.4. Evbuffer performance improvements 456 457 The EVBUFFER_EOL_CRLF line-ending type is now much faster, thanks to 458 smart optimizations. 459 4602.5. HTTP performance improvements 461 462 o Performance tweak to evhttp_parse_request_line. (aee1a97 Mark Ellzey) 463 o Add missing break to evhttp_parse_request_line (0fcc536) 464 4652.6. Coarse timers by default on Linux 466 467 Due to limitations of the epoll interface, Libevent programs using epoll 468 have not previously been able to wait for timeouts with accuracy smaller 469 than 1 millisecond. But Libevent had been using CLOCK_MONOTONIC for 470 timekeeping on Linux, which is needlessly expensive: CLOCK_MONOTONIC_COARSE 471 has approximately the resolution corresponding to epoll, and is much faster 472 to invoke than CLOCK_MONOTONIC. 473 474 To disable coarse timers, and get a more plausible precision, use the 475 new EVENT_BASE_FLAG_PRECISE_TIMER flag when setting up your event base. 476 4773. Backend/OS-specific improvements 478 4793.1. Linux-specific improvements 480 481 The logic for deciding which arguements to use with epoll_ctl() is now 482 a table-driven lookup, rather than the previous pile of cascading 483 branches. This should minimize epoll_ctl() calls and make the epoll 484 code run a little faster on change-heavy loads. 485 486 Libevent now takes advantage of Linux's support for enhanced APIs 487 (e.g., SOCK_CLOEXEC, SOCK_NONBLOCK, accept4, pipe2) that allow us to 488 simultaneously create a socket, make it nonblocking, and make it 489 close-on-exec. This should save syscalls throughout our codebase, and 490 avoid race-conditions if an exec() occurs after a socket is socket is 491 created but before we can make it close-on-execute on it. 492 4933.2. Windows-specific improvements 494 495 We now use GetSystemTimeAsFileTime to implement gettimeofday. It's 496 significantly faster and more accurate than our old ftime()-based approach. 497 4983.3. Improvements in the solaris evport backend. 499 500 The evport backend has been updated to use many of the infrastructure 501 improvements from Libevent 2.0. Notably, it keeps track of per-fd 502 information using the evmap infrastructure, and removes a number of 503 linear scans over recently-added events. This last change makes it 504 efficient to receive many more events per evport_getn() call, thereby 505 reducing evport overhead in general. 506 5073.4. OSX backend improvements 508 509 The OSX select backend doesn't like to have more than a certain number 510 of fds set unless an "unlimited select" option has been set. 511 Therefore, we now set it. 512 5133.5. Monotonic clocks on even more platforms 514 515 Libevent previously used a monotonic clock for its internal timekeeping 516 only on platforms supporting the POSIX clock_gettime() interface. Now, 517 Libevent has support for monotonic clocks on OSX and Windows too, and a 518 fallback implementation for systems without monotonic clocks that will at 519 least keep time running forwards. 520 521 Using monotonic timers makes Libevent more resilient to changes in the 522 system time, as can happen in small amounts due to clock adjustments from 523 NTP, or in large amounts due to users who move their system clocks all over 524 the timeline in order to keep nagware from nagging them. 525 5263.6. Faster cross-thread notification on kqueue 527 528 When a thread other than the one in which the main event loop is 529 running needs to wake the thread running the main event loop, Libevent 530 usually writes to a socketpair in order to force the main event loop 531 to wake up. On Linux, we've been able to use eventfd() instead. Now 532 on BSD and OSX systems (any anywhere else that has kqueue with the 533 EVFILT_USER extension), we can use EVFILT_USER to wake up the main 534 thread from kqueue. This should be a tiny bit faster than the 535 previous approach. 536 5374. Infrastructure improvements 538 5394.1. Faster tests 540 541 I've spent some time to try to make the unit tests run faster in 542 Libevent 2.1. Nearly all of this was a matter of searching slow tests 543 for unreasonably long timeouts, and cutting them down to reasonably 544 long delays, though on one or two cases I actually had to parallelize 545 an operation or improve an algorithm. 546 547 On my desktop, a full "make verify" run of Libevent 2.0.18-stable 548 requires about 218 seconds. Libevent 2.1.1-alpha cuts this down to 549 about 78 seconds. 550 551 Faster unit tests are great, since they let programmers test their 552 changes without losing their train of thought. 553 5544.2. Finicky tests are now off-by-default 555 556 The Tinytest unit testing framework now supports optional tests, and 557 Libevent uses them. By default, Libevent's unit testing framework 558 does not run tests that require a working network, and does not run 559 tests that tend to fail on heavily loaded systems because of timing 560 issues. To re-enable all tests, run ./test/regress using the "@all" 561 alias. 562 5634.3. Modernized use of autotools 564 565 Our autotools-based build system has been updated to build without 566 warnings on recent autoconf/automake versions. 567 568 Libevent's autotools makefiles are no longer recursive. This allows 569 make to use the maximum possible parallelism to do the minimally 570 necessary amount of work. See Peter Miller's "Recursive Make 571 Considered Harmful" at http://miller.emu.id.au/pmiller/books/rmch/ for 572 more information here. 573 574 We now use the "quiet build" option to suppress distracting messages 575 about which commandlines are running. You can get them back with 576 "make V=1". 577 5784.4. Portability 579 580 Libevent now uses large-file support internally on platforms where it 581 matters. You shouldn't need to set _LARGEFILE or OFFSET_BITS or 582 anything magic before including the Libevent headers, either, since 583 Libevent now sets the size of ev_off_t to the size of off_t that it 584 received at compile time, not to some (possibly different) size based 585 on current macro definitions when your program is building. 586 587 We now also use the Autoconf AC_USE_SYSTEM_EXTENSIONS mechanism to 588 enable per-system macros needed to enable not-on-by-default features. 589 Unlike the rest of the autoconf macros, we output these to an 590 internal-use-only evconfig-private.h header, since their names need to 591 survive unmangled. This lets us build correctly on more platforms, 592 and avoid inconsistencies when some files define _GNU_SOURCE and 593 others don't. 594 595 Libevent now tries to detect OpenSSL via pkg-config. 596 5974.5. Standards conformance 598 599 Previous Libevent versions had no consistent convention for internal 600 vs external identifiers, and used identifiers starting with the "_" 601 character throughout the codebase. That's no good, since the C 602 standard says that identifiers beginning with _ are reserved. I'm not 603 aware of having any collisions with system identifiers, but it's best 604 to fix these things before they cause trouble. 605 606 We now avoid all use of the _identifiers in the Libevent source code. 607 These changes were made *mainly* through the use of automated scripts, 608 so there shouldn't be any mistakes, but you never know. 609 610 As an exception, the names _EVENT_LOG_DEBUG, _EVENT_LOG_MSG_, 611 _EVENT_LOG_WARN, and _EVENT_LOG_ERR are still exposed in event.h: they 612 are now deprecated, but to support older code, they will need to stay 613 around for a while. New code should use EVENT_LOG_DEBUG, 614 EVENT_LOG_MSG, EVENT_LOG_WARN, and EVENT_LOG_ERR instead. 615 6164.6. Event and callback refactoring 617 618 As a simplification and optimization to Libevent's "deferred callback" 619 logic (introduced in 2.0 to avoid callback recursion), Libevent now 620 treats all of its deferrable callback types using the same logic it 621 uses for active events. Now deferred events no longer cause priority 622 inversion, no longer require special code to cancel them, and so on. 623 624 Regular events and deferred callbacks now both descend from an 625 internal light-weight event_callback supertype, and both support 626 priorities and take part in the other anti-priority-inversion 627 mechanisms in Libevent. 628 629 To avoid starvation from callback recursion (which was the reason we 630 introduced "deferred callbacks" in the first place) the implementation 631 now allows an event callback to be scheduled as "active later": 632 instead of running in the current iteration of the event loop, it runs 633 in the next one. 634 6355. Testing 636 637 Libevent's test coverage level is more or less unchanged since before: 638 we still have over 80% line coverage in our tests on Linux and OSX. 639 There are some under-tested modules, though: we need to fix those. 640