1290001Sglebius What's new in Libevent 2.1 2290001Sglebius Nick Mathewson 3290001Sglebius 4290001Sglebius0. Before we start 5290001Sglebius 6290001Sglebius0.1. About this document 7290001Sglebius 8290001Sglebius This document describes the key differences between Libevent 2.0 and 9290001Sglebius Libevent 2.1, from a user's point of view. It's a work in progress. 10290001Sglebius 11290001Sglebius For better documentation about libevent, see the links at 12290001Sglebius http://libevent.org/ 13290001Sglebius 14290001Sglebius Libevent 2.1 would not be possible without the generous help of 15290001Sglebius numerous volunteers. For a list of who did what in Libevent 2.1, 16290001Sglebius please see the ChangeLog! 17290001Sglebius 18290001Sglebius NOTE: I am very sure that I missed some thing on this list. Caveat 19290001Sglebius haxxor. 20290001Sglebius 21290001Sglebius0.2. Where to get help 22290001Sglebius 23290001Sglebius Try looking at the other documentation too. All of the header files 24290001Sglebius have documentation in the doxygen format; this gets turned into nice 25290001Sglebius HTML and linked to from the libevent.org website. 26290001Sglebius 27290001Sglebius There is a work-in-progress book with reference manual at 28290001Sglebius http://www.wangafu.net/~nickm/libevent-book/ . 29290001Sglebius 30290001Sglebius You can ask questions on the #libevent IRC channel at irc.oftc.net or 31290001Sglebius on the mailing list at libevent-users@freehaven.net. The mailing list 32290001Sglebius is subscribers-only, so you will need to subscribe before you post. 33290001Sglebius 34290001Sglebius0.3. Compatibility 35290001Sglebius 36290001Sglebius Our source-compatibility policy is that correct code (that is to say, 37290001Sglebius code that uses public interfaces of Libevent and relies only on their 38290001Sglebius documented behavior) should have forward source compatibility: any 39290001Sglebius such code that worked with a previous version of Libevent should work 40290001Sglebius with this version too. 41290001Sglebius 42290001Sglebius We don't try to do binary compatibility except within stable release 43290001Sglebius series, so binaries linked against any version of Libevent 2.0 will 44290001Sglebius probably need to be recompiled against Libevent 2.1.4-alpha if you 45290001Sglebius want to use it. It is probable that we'll break binary compatibility 46290001Sglebius again before Libevent 2.1 is stable. 47290001Sglebius 48290001Sglebius1. New APIs and features 49290001Sglebius 50290001Sglebius1.1. New ways to build libevent 51290001Sglebius 52290001Sglebius We now provide an --enable-gcc-hardening configure option to turn on 53290001Sglebius GCC features designed for increased code security. 54290001Sglebius 55290001Sglebius There is also an --enable-silent-rules configure option to make 56290001Sglebius compilation run more quietly with automake 1.11 or later. 57290001Sglebius 58290001Sglebius You no longer need to use the --enable-gcc-warnings option to turn on 59290001Sglebius all of the GCC warnings that Libevent uses. The only change from 60290001Sglebius using that option now is to turn warnings into errors. 61290001Sglebius 62290001Sglebius For IDE users, files that are not supposed to be built are now 63290001Sglebius surrounded with appropriate #ifdef lines to keep your IDE from getting 64290001Sglebius upset. 65290001Sglebius 66290001Sglebius There is now an alternative cmake-based build process; cmake users 67290001Sglebius should see the relevant sections in the README. 68290001Sglebius 69290001Sglebius 70290001Sglebius1.2. New functions for events and the event loop 71290001Sglebius 72290001Sglebius If you're running Libevent with multiple event priorities, you might 73290001Sglebius want to make sure that Libevent checks for new events frequently, so 74290001Sglebius that time-consuming or numerous low-priority events don't keep it from 75290001Sglebius checking for new high-priority events. You can now use the 76290001Sglebius event_config_set_max_dispatch_interval() interface to ensure that the 77290001Sglebius loop checks for new events either every N microseconds, every M 78290001Sglebius callbacks, or both. 79290001Sglebius 80290001Sglebius When configuring an event base, you can now choose whether you want 81290001Sglebius timers to be more efficient, or more precise. (This only has effect 82290001Sglebius on Linux for now.) Timers are efficient by default: to select more 83290001Sglebius precise timers, use the EVENT_BASE_FLAG_PRECISE_TIMER flag when 84290001Sglebius constructing the event_config, or set the EVENT_PRECISE_TIMER 85290001Sglebius environment variable to a non-empty string. 86290001Sglebius 87290001Sglebius There is an EVLOOP_NO_EXIT_ON_EMPTY flag that tells event_base_loop() 88290001Sglebius to keep looping even when there are no pending events. (Ordinarily, 89290001Sglebius event_base_loop() will exit as soon as no events are pending.) 90290001Sglebius 91290001Sglebius Past versions of Libevent have been annoying to use with some 92290001Sglebius memory-leak-checking tools, because Libevent allocated some global 93290001Sglebius singletons but provided no means to free them. There is now a 94290001Sglebius function, libevent_global_shutdown(), that you can use to free all 95290001Sglebius globally held resources before exiting, so that your leak-check tools 96290001Sglebius don't complain. (Note: this function doesn't free non-global things 97290001Sglebius like events, bufferevents, and so on; and it doesn't free anything 98290001Sglebius that wouldn't otherwise get cleaned up by the operating system when 99290001Sglebius your process exit()s. If you aren't using a leak-checking tool, there 100290001Sglebius is not much reason to call libevent_global_shutdown().) 101290001Sglebius 102290001Sglebius There is a new event_base_get_npriorities() function to return the 103290001Sglebius number of priorities set in the event base. 104290001Sglebius 105290001Sglebius Libevent 2.0 added an event_new() function to construct a new struct 106290001Sglebius event on the heap. Unfortunately, with event_new(), there was no 107290001Sglebius equivalent for: 108290001Sglebius 109290001Sglebius struct event ev; 110290001Sglebius event_assign(&ev, base, fd, EV_READ, callback, &ev); 111290001Sglebius 112290001Sglebius In other words, there was no easy way for event_new() to set up an 113290001Sglebius event so that the event itself would be its callback argument. 114290001Sglebius Libevent 2.1 lets you do this by passing "event_self_cbarg()" as the 115290001Sglebius callback argument: 116290001Sglebius 117290001Sglebius struct event *evp; 118290001Sglebius evp = event_new(base, fd, EV_READ, callback, 119290001Sglebius event_self_cbarg()); 120290001Sglebius 121290001Sglebius There's also a new event_base_get_running_event() function you can 122290001Sglebius call from within a Libevent callback to get a pointer to the current 123290001Sglebius event. This should never be strictly necessary, but it's sometimes 124290001Sglebius convenient. 125290001Sglebius 126290001Sglebius The event_base_once() function used to leak some memory if the event 127290001Sglebius that it added was never actually triggered. Now, its memory is 128290001Sglebius tracked in the event_base and freed when the event_base is freed. 129290001Sglebius Note however that Libevent doesn't know how to free any information 130290001Sglebius passed as the callback argument to event_base_once is still something 131290001Sglebius you'll might need a way to de-allocate yourself. 132290001Sglebius 133290001Sglebius There is an event_get_priority() function to return an event's 134290001Sglebius priority. 135290001Sglebius 136290001Sglebius By analogy to event_base_loopbreak(), there is now an 137290001Sglebius event_base_loopcontinue() that tells Libevent to stop processing 138290001Sglebius active event callbacks, and re-scan for new events right away. 139290001Sglebius 140290001Sglebius There's a function, event_base_foreach_event(), that can iterate over 141290001Sglebius every event currently pending or active on an event base, and invoke a 142290001Sglebius user-supplied callback on each. The callback must not alter the events 143290001Sglebius or add or remove anything to the event base. 144290001Sglebius 145290001Sglebius We now have an event_remove_timer() function to remove the timeout on 146290001Sglebius an event while leaving its socket and/or signal triggers unchanged. 147290001Sglebius (If we were designing the API from scratch, this would be the behavior 148290001Sglebius of "event_add(ev, NULL)" on an already-added event with a timeout. But 149290001Sglebius that's a no-op in past versions of Libevent, and we don't want to 150290001Sglebius break compatibility.) 151290001Sglebius 152290001Sglebius You can use the new event_base_get_num_events() function to find the 153290001Sglebius number of events active or pending on an event_base. To find the 154290001Sglebius largest number of events that there have been since the last call, use 155290001Sglebius event_base_get_max_events(). 156290001Sglebius 157290001Sglebius You can now activate all the events waiting for a given fd or signal 158290001Sglebius using the event_base_active_by_fd() and event_base_active_by_signal() 159290001Sglebius APIs. 160290001Sglebius 161290001Sglebius On backends that support it (currently epoll), there is now an 162290001Sglebius EV_CLOSED flag that programs can use to detect when a socket has 163290001Sglebius closed without having to read all the bytes until receiving an EOF. 164290001Sglebius 165290001Sglebius1.3. Event finalization 166290001Sglebius 167290001Sglebius [NOTE: This is an experimental feature in Libevent 2.1.3-alpha. Though 168290001Sglebius it seems solid so far, its API might change between now and the first 169290001Sglebius release candidate for Libevent 2.1.] 170290001Sglebius 171290001Sglebius1.3.1. Why event finalization? 172290001Sglebius 173290001Sglebius Libevent 2.1 now supports an API for safely "finalizing" events that 174290001Sglebius might be running in multiple threads, and provides a way to slightly 175290001Sglebius change the semantics of event_del() to prevent deadlocks in 176290001Sglebius multithreaded programs. 177290001Sglebius 178290001Sglebius To motivate this feature, consider the following code, in the context 179290001Sglebius of a mulithreaded Libevent application: 180290001Sglebius 181290001Sglebius struct connection *conn = event_get_callback_arg(ev); 182290001Sglebius event_del(ev); 183290001Sglebius connection_free(conn); 184290001Sglebius 185290001Sglebius Suppose that the event's callback might be running in another thread, 186290001Sglebius and using the value of "conn" concurrently. We wouldn't want to 187290001Sglebius execute the connection_free() call until "conn" is no longer in use. 188290001Sglebius How can we make this code safe? 189290001Sglebius 190290001Sglebius Libevent 2.0 answered that question by saying that the event_del() 191290001Sglebius call should block if the event's callback is running in another 192290001Sglebius thread. That way, we can be sure that event_del() has canceled the 193290001Sglebius callback (if the callback hadn't started running yet), or has waited 194290001Sglebius for the callback to finish. 195290001Sglebius 196290001Sglebius But now suppose that the data structure is protected by a lock, and we 197290001Sglebius have the following code: 198290001Sglebius 199290001Sglebius void check_disable(struct connection *connection) { 200290001Sglebius lock(connection); 201290001Sglebius if (should_stop_reading(connection)) 202290001Sglebius event_del(connection->read_event); 203290001Sglebius unlock(connection); 204290001Sglebius } 205290001Sglebius 206290001Sglebius What happens when we call check_disable() from a callback and from 207290001Sglebius another thread? Let's say that the other thread gets the lock 208290001Sglebius first. If it decides to call event_del(), it will wait for the 209290001Sglebius callback to finish. But meanwhile, the callback will be waiting for 210290001Sglebius the lock on the connection. Since each threads is waiting for the 211290001Sglebius other one to release a resource, the program will deadlock. 212290001Sglebius 213290001Sglebius This bug showed up in multithreaded bufferevent programs in 2.1, 214290001Sglebius particularly when freeing bufferevents. (For more information, see 215290001Sglebius the "Deadlock when calling bufferevent_free from an other thread" 216290001Sglebius thread on libevent-users starting on 6 August 2012 and running through 217290001Sglebius February of 2013. You might also like to read my earlier writeup at 218290001Sglebius http://archives.seul.org/libevent/users/Feb-2012/msg00053.html and 219290001Sglebius the ensuing discussion.) 220290001Sglebius 221290001Sglebius1.3.2. The EV_FINALIZE flag and avoiding deadlock 222290001Sglebius 223290001Sglebius To prevent the deadlock condition described above, Libevent 224290001Sglebius 2.1.3-alpha adds a new flag, "EV_FINALIZE". You can pass it to 225290001Sglebius event_new() and event_assign() along with EV_READ, EV_WRITE, and the 226290001Sglebius other event flags. 227290001Sglebius 228290001Sglebius When an event is constructed with the EV_FINALIZE flag, event_del() 229290001Sglebius will not block on that event, even when the event's callback is 230290001Sglebius running in another thread. By using EV_FINALIZE, you are therefore 231290001Sglebius promising not to use the "event_del(ev); free(event_get_callback_arg(ev));" 232290001Sglebius pattern, but rather to use one of the finalization functions below to 233290001Sglebius clean up the event. 234290001Sglebius 235290001Sglebius EV_FINALIZE has no effect on a single-threaded program, or on a 236290001Sglebius program where events are only used from one thread. 237290001Sglebius 238290001Sglebius 239290001Sglebius There are also two new variants of event_del() that you can use for 240290001Sglebius more fine-grained control: 241290001Sglebius event_del_noblock(ev) 242290001Sglebius event_del_block(ev) 243290001Sglebius The event_del_noblock() function will never block, even if the event 244290001Sglebius callback is running in another thread and doesn't have the EV_FINALIZE 245290001Sglebius flag. The event_del_block() function will _always_ block if the event 246290001Sglebius callback is running in another thread, even if the event _does_ have 247290001Sglebius the EV_FINALIZE flag. 248290001Sglebius 249290001Sglebius [A future version of Libevent may have a way to make the EV_FINALIZE 250290001Sglebius flag the default.] 251290001Sglebius 252290001Sglebius1.3.3. Safely finalizing events 253290001Sglebius 254290001Sglebius To safely tear down an event that may be running, Libevent 2.1.3-alpha 255290001Sglebius introduces event_finalize() and event_free_finalize(). You call them 256290001Sglebius on an event, and provide a finalizer callback to be run on the event 257290001Sglebius and its callback argument once the event is definitely no longer 258290001Sglebius running. 259290001Sglebius 260290001Sglebius With event_free_finalize(), the event is also freed once the finalizer 261290001Sglebius callback has been invoked. 262290001Sglebius 263290001Sglebius A finalized event cannot be re-added or activated. The finalizer 264290001Sglebius callback must not add events, activate events, or attempt to 265290001Sglebius "resucitate" the event being finalized in any way. 266290001Sglebius 267290001Sglebius If any finalizer callbacks are pending as the event_base is being 268290001Sglebius freed, they will be invoked. You can override this behavior with the 269290001Sglebius new function event_base_free_nofinalize(). 270290001Sglebius 271290001Sglebius1.4. New debugging features 272290001Sglebius 273290001Sglebius You can now turn on debug logs at runtime using a new function, 274290001Sglebius event_enable_debug_logging(). 275290001Sglebius 276290001Sglebius The event_enable_lock_debugging() function is now spelled correctly. 277290001Sglebius You can still use the old "event_enable_lock_debuging" name, though, 278290001Sglebius so your old programs shouldnt' break. 279290001Sglebius 280290001Sglebius There's also been some work done to try to make the debugging logs 281290001Sglebius more generally useful. 282290001Sglebius 283290001Sglebius1.5. New evbuffer functions 284290001Sglebius 285290001Sglebius In Libevent 2.0, we introduced evbuffer_add_file() to add an entire 286290001Sglebius file's contents to an evbuffer, and then send them using sendfile() or 287290001Sglebius mmap() as appropriate. This API had some drawbacks, however. 288290001Sglebius Notably, it created one mapping or fd for every instance of the same 289290001Sglebius file added to any evbuffer. Also, adding a file to an evbuffer could 290290001Sglebius make that buffer unusable with SSL bufferevents, filtering 291290001Sglebius bufferevents, and any code that tried to read the contents of the 292290001Sglebius evbuffer. 293290001Sglebius 294290001Sglebius Libevent 2.1 adds a new evbuffer_file_segment API to solve these 295290001Sglebius problems. Now, you can use evbuffer_file_segment_new() to construct a 296290001Sglebius file-segment object, and evbuffer_add_file_segment() to insert it (or 297290001Sglebius part of it) into an evbuffer. These segments avoid creating redundant 298290001Sglebius maps or fds. Better still, the code is smart enough (when the OS 299290001Sglebius supports sendfile) to map the file when that's necessary, and use 300290001Sglebius sendfile() otherwise. 301290001Sglebius 302290001Sglebius File segments can receive callback functions that are invoked when the 303290001Sglebius file segments are freed. 304290001Sglebius 305290001Sglebius The evbuffer_ptr interface has been extended so that an evbuffer_ptr 306290001Sglebius can now yield a point just after the end of the buffer. This makes 307290001Sglebius many algorithms simpler to implement. 308290001Sglebius 309290001Sglebius There's a new evbuffer_add_buffer() interface that you can use to add 310290001Sglebius one buffer to another nondestructively. When you say 311290001Sglebius evbuffer_add_buffer_reference(outbuf, inbuf), outbuf now contains a 312290001Sglebius reference to the contents of inbuf. 313290001Sglebius 314290001Sglebius To aid in adding data in bulk while minimizing evbuffer calls, there 315290001Sglebius is an evbuffer_add_iovec() function. 316290001Sglebius 317290001Sglebius There's a new evbuffer_copyout_from() variant function to enable 318290001Sglebius copying data nondestructively from the middle of a buffer. 319290001Sglebius 320290001Sglebius evbuffer_readln() now supports an EVBUFFER_EOL_NUL argument to fetch 321290001Sglebius NUL-terminated strings from buffers. 322290001Sglebius 323290001Sglebius1.6. New functions and features: bufferevents 324290001Sglebius 325290001Sglebius You can now use the bufferevent_getcb() function to find out a 326290001Sglebius bufferevent's callbacks. Previously, there was no supported way to do 327290001Sglebius that. 328290001Sglebius 329290001Sglebius The largest chunk readable or writeable in a single bufferevent 330290001Sglebius callback is no longer hardcoded; it's now configurable with 331290001Sglebius the new functions bufferevent_set_max_single_read() and 332290001Sglebius bufferevent_set_max_single_write(). 333290001Sglebius 334290001Sglebius For consistency, OpenSSL bufferevents now make sure to always set one 335290001Sglebius of BEV_EVENT_READING or BEV_EVENT_WRITING when invoking an event 336290001Sglebius callback. 337290001Sglebius 338290001Sglebius Calling bufferevent_set_timeouts(bev, NULL, NULL) now removes the 339290001Sglebius timeouts from socket and ssl bufferevents correctly. 340290001Sglebius 341290001Sglebius You can find the priority at which a bufferevent runs with 342290001Sglebius bufferevent_get_priority(). 343290001Sglebius 344290001Sglebius The function bufferevent_get_token_bucket_cfg() can retrieve the 345290001Sglebius rate-limit settings for a bufferevent; bufferevent_getwatermark() can 346290001Sglebius return a bufferevent's current watermark settings. 347290001Sglebius 348290001Sglebius You can manually trigger a bufferevent's callbacks via 349290001Sglebius bufferevent_trigger() and bufferevent_trigger_event(). 350290001Sglebius 351290001Sglebius1.7. New functions and features: evdns 352290001Sglebius 353290001Sglebius The previous evdns interface used an "open a test UDP socket" trick in 354290001Sglebius order to detect IPv6 support. This was a hack, since it would 355290001Sglebius sometimes badly confuse people's firewall software, even though no 356290001Sglebius packets were sent. The current evdns interface-detection code uses 357290001Sglebius the appropriate OS functions to see which interfaces are configured. 358290001Sglebius 359290001Sglebius The evdns_base_new() function now has multiple possible values for its 360290001Sglebius second (flags) argument. Using 1 and 0 have their old meanings, though the 361290001Sglebius 1 flag now has a symbolic name of EVDNS_BASE_INITIALIZE_NAMESERVERS. 362290001Sglebius A second flag is now supported too: the EVDNS_BASE_DISABLE_WHEN_INACTIVE 363290001Sglebius flag, which tells the evdns_base that it should not prevent Libevent from 364290001Sglebius exiting while it has no DNS requests in progress. 365290001Sglebius 366290001Sglebius There is a new evdns_base_clear_host_addresses() function to remove 367290001Sglebius all the /etc/hosts addresses registered with an evdns instance. 368290001Sglebius 369290001Sglebius1.8. New functions and features: evconnlistener 370290001Sglebius 371290001Sglebius Libevent 2.1 adds the following evconnlistener flags: 372290001Sglebius 373290001Sglebius LEV_OPT_DEFERRED_ACCEPT -- Tells the OS that it doesn't need to 374290001Sglebius report sockets as having arrived until the initiator has sent some 375290001Sglebius data too. This can greatly improve performance with protocols like 376290001Sglebius HTTP where the client always speaks first. On operating systems 377290001Sglebius that don't support this functionality, this option has no effect. 378290001Sglebius 379290001Sglebius LEV_OPT_DISABLED -- Creates an evconnlistener in the disabled (not 380290001Sglebius listening) state. 381290001Sglebius 382290001Sglebius Libevent 2.1 changes the behavior of the LEV_OPT_CLOSE_ON_EXEC 383290001Sglebius flag. Previously, it would apply to the listener sockets, but not to 384290001Sglebius the accepted sockets themselves. That's almost never what you want. 385290001Sglebius Now, it applies both to the listener and the accepted sockets. 386290001Sglebius 387290001Sglebius1.9. New functions and features: evhttp 388290001Sglebius 389290001Sglebius ********************************************************************** 390290001Sglebius NOTE: The evhttp module will eventually be deprecated in favor of Mark 391290001Sglebius Ellzey's libevhtp library. Don't worry -- this won't happen until 392290001Sglebius libevhtp provides every feature that evhttp does, and provides a 393290001Sglebius compatible interface that applications can use to migrate. 394290001Sglebius ********************************************************************** 395290001Sglebius 396290001Sglebius Previously, you could only set evhttp timeouts in increments of one 397290001Sglebius second. Now, you can use evhttp_set_timeout_tv() and 398290001Sglebius evhttp_connection_set_timeout_tv() to configure 399290001Sglebius microsecond-granularity timeouts. 400290001Sglebius 401290001Sglebius There are a new pair of functions: evhttp_set_bevcb() and 402290001Sglebius evhttp_connection_base_bufferevent_new(), that you can use to 403290001Sglebius configure which bufferevents will be used for incoming and outgoing 404290001Sglebius http connections respectively. These functions, combined with SSL 405290001Sglebius bufferevents, should enable HTTPS support. 406290001Sglebius 407290001Sglebius There's a new evhttp_foreach_bound_socket() function to iterate over 408290001Sglebius every listener on an evhttp object. 409290001Sglebius 410290001Sglebius Whitespace between lines in headers is now folded into a single space; 411290001Sglebius whitespace at the end of a header is now removed. 412290001Sglebius 413290001Sglebius The socket errno value is now preserved when invoking an http error 414290001Sglebius callback. 415290001Sglebius 416290001Sglebius There's a new kind of request callback for errors; you can set it with 417290001Sglebius evhttp_request_set_error_cb(). It gets called when there's a request error, 418290001Sglebius and actually reports the error code and lets you figure out which request 419290001Sglebius failed. 420290001Sglebius 421290001Sglebius You can navigate from an evhttp_connection back to its evhttp with the 422290001Sglebius new evhttp_connection_get_server() function. 423290001Sglebius 424290001Sglebius You can override the default HTTP Content-Type with the new 425290001Sglebius evhttp_set_default_content_type() function 426290001Sglebius 427290001Sglebius There's a new evhttp_connection_get_addr() API to return the peer 428290001Sglebius address of an evhttp_connection. 429290001Sglebius 430290001Sglebius The new evhttp_send_reply_chunk_with_cb() is a variant of 431290001Sglebius evhttp_send_reply_chunk() with a callback to be invoked when the 432290001Sglebius chunk is sent. 433290001Sglebius 434290001Sglebius The evhttp_request_set_header_cb() facility adds a callback to be 435290001Sglebius invoked while parsing headers. 436290001Sglebius 437290001Sglebius The evhttp_request_set_on_complete_cb() facility adds a callback to be 438290001Sglebius invoked on request completion. 439290001Sglebius 440290001Sglebius1.10. New functions and features: evutil 441290001Sglebius 442290001Sglebius There's a function "evutil_secure_rng_set_urandom_device_file()" that 443290001Sglebius you can use to override the default file that Libevent uses to seed 444290001Sglebius its (sort-of) secure RNG. 445290001Sglebius 446290001Sglebius2. Cross-platform performance improvements 447290001Sglebius 448290001Sglebius2.1. Better data structures 449290001Sglebius 450290001Sglebius We replaced several users of the sys/queue.h "TAILQ" data structure 451290001Sglebius with the "LIST" data structure. Because this data type doesn't 452290001Sglebius require FIFO access, it requires fewer pointer checks and 453290001Sglebius manipulations to keep it in line. 454290001Sglebius 455290001Sglebius All previous versions of Libevent have kept every pending (added) 456290001Sglebius event in an "eventqueue" data structure. Starting in Libevent 2.0, 457290001Sglebius however, this structure became redundant: every pending timeout event 458290001Sglebius is stored in the timeout heap or in one of the common_timeout queues, 459290001Sglebius and every pending fd or signal event is stored in an evmap. Libevent 460290001Sglebius 2.1 removes this data structure, and thereby saves all of the code 461290001Sglebius that we'd been using to keep it updated. 462290001Sglebius 463290001Sglebius2.2. Faster activations and timeouts 464290001Sglebius 465290001Sglebius It's a common pattern in older code to use event_base_once() with a 466290001Sglebius 0-second timeout to ensure that a callback will get run 'as soon as 467290001Sglebius possible' in the current iteration of the Libevent loop. We optimize 468290001Sglebius this case by calling event_active() directly, and bypassing the 469290001Sglebius timeout pool. (People who are using this pattern should also consider 470290001Sglebius using event_active() themselves.) 471290001Sglebius 472290001Sglebius Libevent 2.0 would wake up a polling event loop whenever the first 473290001Sglebius timeout in the event loop was adjusted--whether it had become earlier 474290001Sglebius or later. We now only notify the event loop when a change causes the 475290001Sglebius expiration time to become _sooner_ than it would have been otherwise. 476290001Sglebius 477290001Sglebius The timeout heap code is now optimized to perform fewer comparisons 478290001Sglebius and shifts when changing or removing a timeout. 479290001Sglebius 480290001Sglebius Instead of checking for a wall-clock time jump every time we call 481290001Sglebius clock_gettime(), we now check only every 5 seconds. This should save 482290001Sglebius a huge number of gettimeofday() calls. 483290001Sglebius 484290001Sglebius2.3. Microoptimizations 485290001Sglebius 486290001Sglebius Internal event list maintainance no longer use the antipattern where 487290001Sglebius we have one function with multiple totally independent behaviors 488290001Sglebius depending on an argument: 489290001Sglebius #define OP1 1 490290001Sglebius #define OP2 2 491290001Sglebius #define OP3 3 492290001Sglebius void func(int operation, struct event *ev) { 493290001Sglebius switch (op) { 494290001Sglebius ... 495290001Sglebius } 496290001Sglebius } 497290001Sglebius Instead, these functions are now split into separate functions for 498290001Sglebius each operation: 499290001Sglebius void func_op1(struct event *ev) { ... } 500290001Sglebius void func_op2(struct event *ev) { ... } 501290001Sglebius void func_op3(struct event *ev) { ... } 502290001Sglebius 503290001Sglebius This produces better code generation and inlining decisions on some 504290001Sglebius compilers, and makes the code easier to read and check. 505290001Sglebius 506290001Sglebius2.4. Evbuffer performance improvements 507290001Sglebius 508290001Sglebius The EVBUFFER_EOL_CRLF line-ending type is now much faster, thanks to 509290001Sglebius smart optimizations. 510290001Sglebius 511290001Sglebius2.5. HTTP performance improvements 512290001Sglebius 513290001Sglebius o Performance tweak to evhttp_parse_request_line. (aee1a97 Mark Ellzey) 514290001Sglebius o Add missing break to evhttp_parse_request_line (0fcc536) 515290001Sglebius 516290001Sglebius2.6. Coarse timers by default on Linux 517290001Sglebius 518290001Sglebius Due to limitations of the epoll interface, Libevent programs using epoll 519290001Sglebius have not previously been able to wait for timeouts with accuracy smaller 520290001Sglebius than 1 millisecond. But Libevent had been using CLOCK_MONOTONIC for 521290001Sglebius timekeeping on Linux, which is needlessly expensive: CLOCK_MONOTONIC_COARSE 522290001Sglebius has approximately the resolution corresponding to epoll, and is much faster 523290001Sglebius to invoke than CLOCK_MONOTONIC. 524290001Sglebius 525290001Sglebius To disable coarse timers, and get a more plausible precision, use the 526290001Sglebius new EVENT_BASE_FLAG_PRECISE_TIMER flag when setting up your event base. 527290001Sglebius 528290001Sglebius3. Backend/OS-specific improvements 529290001Sglebius 530290001Sglebius3.1. Linux-specific improvements 531290001Sglebius 532290001Sglebius The logic for deciding which arguements to use with epoll_ctl() is now 533290001Sglebius a table-driven lookup, rather than the previous pile of cascading 534290001Sglebius branches. This should minimize epoll_ctl() calls and make the epoll 535290001Sglebius code run a little faster on change-heavy loads. 536290001Sglebius 537290001Sglebius Libevent now takes advantage of Linux's support for enhanced APIs 538290001Sglebius (e.g., SOCK_CLOEXEC, SOCK_NONBLOCK, accept4, pipe2) that allow us to 539290001Sglebius simultaneously create a socket, make it nonblocking, and make it 540290001Sglebius close-on-exec. This should save syscalls throughout our codebase, and 541290001Sglebius avoid race-conditions if an exec() occurs after a socket is socket is 542290001Sglebius created but before we can make it close-on-execute on it. 543290001Sglebius 544290001Sglebius3.2. Windows-specific improvements 545290001Sglebius 546290001Sglebius We now use GetSystemTimeAsFileTime to implement gettimeofday. It's 547290001Sglebius significantly faster and more accurate than our old ftime()-based approach. 548290001Sglebius 549290001Sglebius3.3. Improvements in the solaris evport backend. 550290001Sglebius 551290001Sglebius The evport backend has been updated to use many of the infrastructure 552290001Sglebius improvements from Libevent 2.0. Notably, it keeps track of per-fd 553290001Sglebius information using the evmap infrastructure, and removes a number of 554290001Sglebius linear scans over recently-added events. This last change makes it 555290001Sglebius efficient to receive many more events per evport_getn() call, thereby 556290001Sglebius reducing evport overhead in general. 557290001Sglebius 558290001Sglebius3.4. OSX backend improvements 559290001Sglebius 560290001Sglebius The OSX select backend doesn't like to have more than a certain number 561290001Sglebius of fds set unless an "unlimited select" option has been set. 562290001Sglebius Therefore, we now set it. 563290001Sglebius 564290001Sglebius3.5. Monotonic clocks on even more platforms 565290001Sglebius 566290001Sglebius Libevent previously used a monotonic clock for its internal timekeeping 567290001Sglebius only on platforms supporting the POSIX clock_gettime() interface. Now, 568290001Sglebius Libevent has support for monotonic clocks on OSX and Windows too, and a 569290001Sglebius fallback implementation for systems without monotonic clocks that will at 570290001Sglebius least keep time running forwards. 571290001Sglebius 572290001Sglebius Using monotonic timers makes Libevent more resilient to changes in the 573290001Sglebius system time, as can happen in small amounts due to clock adjustments from 574290001Sglebius NTP, or in large amounts due to users who move their system clocks all over 575290001Sglebius the timeline in order to keep nagware from nagging them. 576290001Sglebius 577290001Sglebius3.6. Faster cross-thread notification on kqueue 578290001Sglebius 579290001Sglebius When a thread other than the one in which the main event loop is 580290001Sglebius running needs to wake the thread running the main event loop, Libevent 581290001Sglebius usually writes to a socketpair in order to force the main event loop 582290001Sglebius to wake up. On Linux, we've been able to use eventfd() instead. Now 583290001Sglebius on BSD and OSX systems (any anywhere else that has kqueue with the 584290001Sglebius EVFILT_USER extension), we can use EVFILT_USER to wake up the main 585290001Sglebius thread from kqueue. This should be a tiny bit faster than the 586290001Sglebius previous approach. 587290001Sglebius 588290001Sglebius4. Infrastructure improvements 589290001Sglebius 590290001Sglebius4.1. Faster tests 591290001Sglebius 592290001Sglebius I've spent some time to try to make the unit tests run faster in 593290001Sglebius Libevent 2.1. Nearly all of this was a matter of searching slow tests 594290001Sglebius for unreasonably long timeouts, and cutting them down to reasonably 595290001Sglebius long delays, though on one or two cases I actually had to parallelize 596290001Sglebius an operation or improve an algorithm. 597290001Sglebius 598290001Sglebius On my desktop, a full "make verify" run of Libevent 2.0.18-stable 599290001Sglebius requires about 218 seconds. Libevent 2.1.1-alpha cuts this down to 600290001Sglebius about 78 seconds. 601290001Sglebius 602290001Sglebius Faster unit tests are great, since they let programmers test their 603290001Sglebius changes without losing their train of thought. 604290001Sglebius 605290001Sglebius4.2. Finicky tests are now off-by-default 606290001Sglebius 607290001Sglebius The Tinytest unit testing framework now supports optional tests, and 608290001Sglebius Libevent uses them. By default, Libevent's unit testing framework 609290001Sglebius does not run tests that require a working network, and does not run 610290001Sglebius tests that tend to fail on heavily loaded systems because of timing 611290001Sglebius issues. To re-enable all tests, run ./test/regress using the "@all" 612290001Sglebius alias. 613290001Sglebius 614290001Sglebius4.3. Modernized use of autotools 615290001Sglebius 616290001Sglebius Our autotools-based build system has been updated to build without 617290001Sglebius warnings on recent autoconf/automake versions. 618290001Sglebius 619290001Sglebius Libevent's autotools makefiles are no longer recursive. This allows 620290001Sglebius make to use the maximum possible parallelism to do the minimally 621290001Sglebius necessary amount of work. See Peter Miller's "Recursive Make 622290001Sglebius Considered Harmful" at http://miller.emu.id.au/pmiller/books/rmch/ for 623290001Sglebius more information here. 624290001Sglebius 625290001Sglebius We now use the "quiet build" option to suppress distracting messages 626290001Sglebius about which commandlines are running. You can get them back with 627290001Sglebius "make V=1". 628290001Sglebius 629290001Sglebius4.4. Portability 630290001Sglebius 631290001Sglebius Libevent now uses large-file support internally on platforms where it 632290001Sglebius matters. You shouldn't need to set _LARGEFILE or OFFSET_BITS or 633290001Sglebius anything magic before including the Libevent headers, either, since 634290001Sglebius Libevent now sets the size of ev_off_t to the size of off_t that it 635290001Sglebius received at compile time, not to some (possibly different) size based 636290001Sglebius on current macro definitions when your program is building. 637290001Sglebius 638290001Sglebius We now also use the Autoconf AC_USE_SYSTEM_EXTENSIONS mechanism to 639290001Sglebius enable per-system macros needed to enable not-on-by-default features. 640290001Sglebius Unlike the rest of the autoconf macros, we output these to an 641290001Sglebius internal-use-only evconfig-private.h header, since their names need to 642290001Sglebius survive unmangled. This lets us build correctly on more platforms, 643290001Sglebius and avoid inconsistencies when some files define _GNU_SOURCE and 644290001Sglebius others don't. 645290001Sglebius 646290001Sglebius Libevent now tries to detect OpenSSL via pkg-config. 647290001Sglebius 648290001Sglebius4.5. Standards conformance 649290001Sglebius 650290001Sglebius Previous Libevent versions had no consistent convention for internal 651290001Sglebius vs external identifiers, and used identifiers starting with the "_" 652290001Sglebius character throughout the codebase. That's no good, since the C 653290001Sglebius standard says that identifiers beginning with _ are reserved. I'm not 654290001Sglebius aware of having any collisions with system identifiers, but it's best 655290001Sglebius to fix these things before they cause trouble. 656290001Sglebius 657290001Sglebius We now avoid all use of the _identifiers in the Libevent source code. 658290001Sglebius These changes were made *mainly* through the use of automated scripts, 659290001Sglebius so there shouldn't be any mistakes, but you never know. 660290001Sglebius 661290001Sglebius As an exception, the names _EVENT_LOG_DEBUG, _EVENT_LOG_MSG_, 662290001Sglebius _EVENT_LOG_WARN, and _EVENT_LOG_ERR are still exposed in event.h: they 663290001Sglebius are now deprecated, but to support older code, they will need to stay 664290001Sglebius around for a while. New code should use EVENT_LOG_DEBUG, 665290001Sglebius EVENT_LOG_MSG, EVENT_LOG_WARN, and EVENT_LOG_ERR instead. 666290001Sglebius 667290001Sglebius4.6. Event and callback refactoring 668290001Sglebius 669290001Sglebius As a simplification and optimization to Libevent's "deferred callback" 670290001Sglebius logic (introduced in 2.0 to avoid callback recursion), Libevent now 671290001Sglebius treats all of its deferrable callback types using the same logic it 672290001Sglebius uses for active events. Now deferred events no longer cause priority 673290001Sglebius inversion, no longer require special code to cancel them, and so on. 674290001Sglebius 675290001Sglebius Regular events and deferred callbacks now both descend from an 676290001Sglebius internal light-weight event_callback supertype, and both support 677290001Sglebius priorities and take part in the other anti-priority-inversion 678290001Sglebius mechanisms in Libevent. 679290001Sglebius 680290001Sglebius To avoid starvation from callback recursion (which was the reason we 681290001Sglebius introduced "deferred callbacks" in the first place) the implementation 682290001Sglebius now allows an event callback to be scheduled as "active later": 683290001Sglebius instead of running in the current iteration of the event loop, it runs 684290001Sglebius in the next one. 685290001Sglebius 686290001Sglebius5. Testing 687290001Sglebius 688290001Sglebius Libevent's test coverage level is more or less unchanged since before: 689290001Sglebius we still have over 80% line coverage in our tests on Linux and OSX. 690290001Sglebius There are some under-tested modules, though: we need to fix those. 691