1*c43e99fdSEd Maste What's new in Libevent 2.1 2*c43e99fdSEd Maste Nick Mathewson 3*c43e99fdSEd Maste 4*c43e99fdSEd Maste0. Before we start 5*c43e99fdSEd Maste 6*c43e99fdSEd Maste0.1. About this document 7*c43e99fdSEd Maste 8*c43e99fdSEd Maste This document describes the key differences between Libevent 2.0 and 9*c43e99fdSEd Maste Libevent 2.1, from a user's point of view. It's a work in progress. 10*c43e99fdSEd Maste 11*c43e99fdSEd Maste For better documentation about libevent, see the links at 12*c43e99fdSEd Maste http://libevent.org/ 13*c43e99fdSEd Maste 14*c43e99fdSEd Maste Libevent 2.1 would not be possible without the generous help of 15*c43e99fdSEd Maste numerous volunteers. For a list of who did what in Libevent 2.1, 16*c43e99fdSEd Maste please see the ChangeLog! 17*c43e99fdSEd Maste 18*c43e99fdSEd Maste NOTE: I am very sure that I missed some thing on this list. Caveat 19*c43e99fdSEd Maste haxxor. 20*c43e99fdSEd Maste 21*c43e99fdSEd Maste0.2. Where to get help 22*c43e99fdSEd Maste 23*c43e99fdSEd Maste Try looking at the other documentation too. All of the header files 24*c43e99fdSEd Maste have documentation in the doxygen format; this gets turned into nice 25*c43e99fdSEd Maste HTML and linked to from the libevent.org website. 26*c43e99fdSEd Maste 27*c43e99fdSEd Maste There is a work-in-progress book with reference manual at 28*c43e99fdSEd Maste http://www.wangafu.net/~nickm/libevent-book/ . 29*c43e99fdSEd Maste 30*c43e99fdSEd Maste You can ask questions on the #libevent IRC channel at irc.oftc.net or 31*c43e99fdSEd Maste on the mailing list at libevent-users@freehaven.net. The mailing list 32*c43e99fdSEd Maste is subscribers-only, so you will need to subscribe before you post. 33*c43e99fdSEd Maste 34*c43e99fdSEd Maste0.3. Compatibility 35*c43e99fdSEd Maste 36*c43e99fdSEd Maste Our source-compatibility policy is that correct code (that is to say, 37*c43e99fdSEd Maste code that uses public interfaces of Libevent and relies only on their 38*c43e99fdSEd Maste documented behavior) should have forward source compatibility: any 39*c43e99fdSEd Maste such code that worked with a previous version of Libevent should work 40*c43e99fdSEd Maste with this version too. 41*c43e99fdSEd Maste 42*c43e99fdSEd Maste We don't try to do binary compatibility except within stable release 43*c43e99fdSEd Maste series, so binaries linked against any version of Libevent 2.0 will 44*c43e99fdSEd Maste probably need to be recompiled against Libevent 2.1.4-alpha if you 45*c43e99fdSEd Maste want to use it. It is probable that we'll break binary compatibility 46*c43e99fdSEd Maste again before Libevent 2.1 is stable. 47*c43e99fdSEd Maste 48*c43e99fdSEd Maste1. New APIs and features 49*c43e99fdSEd Maste 50*c43e99fdSEd Maste1.1. New ways to build libevent 51*c43e99fdSEd Maste 52*c43e99fdSEd Maste We now provide an --enable-gcc-hardening configure option to turn on 53*c43e99fdSEd Maste GCC features designed for increased code security. 54*c43e99fdSEd Maste 55*c43e99fdSEd Maste There is also an --enable-silent-rules configure option to make 56*c43e99fdSEd Maste compilation run more quietly with automake 1.11 or later. 57*c43e99fdSEd Maste 58*c43e99fdSEd Maste You no longer need to use the --enable-gcc-warnings option to turn on 59*c43e99fdSEd Maste all of the GCC warnings that Libevent uses. The only change from 60*c43e99fdSEd Maste using that option now is to turn warnings into errors. 61*c43e99fdSEd Maste 62*c43e99fdSEd Maste For IDE users, files that are not supposed to be built are now 63*c43e99fdSEd Maste surrounded with appropriate #ifdef lines to keep your IDE from getting 64*c43e99fdSEd Maste upset. 65*c43e99fdSEd Maste 66*c43e99fdSEd Maste There is now an alternative cmake-based build process; cmake users 67*c43e99fdSEd Maste should see the relevant sections in the README. 68*c43e99fdSEd Maste 69*c43e99fdSEd Maste 70*c43e99fdSEd Maste1.2. New functions for events and the event loop 71*c43e99fdSEd Maste 72*c43e99fdSEd Maste If you're running Libevent with multiple event priorities, you might 73*c43e99fdSEd Maste want to make sure that Libevent checks for new events frequently, so 74*c43e99fdSEd Maste that time-consuming or numerous low-priority events don't keep it from 75*c43e99fdSEd Maste checking for new high-priority events. You can now use the 76*c43e99fdSEd Maste event_config_set_max_dispatch_interval() interface to ensure that the 77*c43e99fdSEd Maste loop checks for new events either every N microseconds, every M 78*c43e99fdSEd Maste callbacks, or both. 79*c43e99fdSEd Maste 80*c43e99fdSEd Maste When configuring an event base, you can now choose whether you want 81*c43e99fdSEd Maste timers to be more efficient, or more precise. (This only has effect 82*c43e99fdSEd Maste on Linux for now.) Timers are efficient by default: to select more 83*c43e99fdSEd Maste precise timers, use the EVENT_BASE_FLAG_PRECISE_TIMER flag when 84*c43e99fdSEd Maste constructing the event_config, or set the EVENT_PRECISE_TIMER 85*c43e99fdSEd Maste environment variable to a non-empty string. 86*c43e99fdSEd Maste 87*c43e99fdSEd Maste There is an EVLOOP_NO_EXIT_ON_EMPTY flag that tells event_base_loop() 88*c43e99fdSEd Maste to keep looping even when there are no pending events. (Ordinarily, 89*c43e99fdSEd Maste event_base_loop() will exit as soon as no events are pending.) 90*c43e99fdSEd Maste 91*c43e99fdSEd Maste Past versions of Libevent have been annoying to use with some 92*c43e99fdSEd Maste memory-leak-checking tools, because Libevent allocated some global 93*c43e99fdSEd Maste singletons but provided no means to free them. There is now a 94*c43e99fdSEd Maste function, libevent_global_shutdown(), that you can use to free all 95*c43e99fdSEd Maste globally held resources before exiting, so that your leak-check tools 96*c43e99fdSEd Maste don't complain. (Note: this function doesn't free non-global things 97*c43e99fdSEd Maste like events, bufferevents, and so on; and it doesn't free anything 98*c43e99fdSEd Maste that wouldn't otherwise get cleaned up by the operating system when 99*c43e99fdSEd Maste your process exit()s. If you aren't using a leak-checking tool, there 100*c43e99fdSEd Maste is not much reason to call libevent_global_shutdown().) 101*c43e99fdSEd Maste 102*c43e99fdSEd Maste There is a new event_base_get_npriorities() function to return the 103*c43e99fdSEd Maste number of priorities set in the event base. 104*c43e99fdSEd Maste 105*c43e99fdSEd Maste Libevent 2.0 added an event_new() function to construct a new struct 106*c43e99fdSEd Maste event on the heap. Unfortunately, with event_new(), there was no 107*c43e99fdSEd Maste equivalent for: 108*c43e99fdSEd Maste 109*c43e99fdSEd Maste struct event ev; 110*c43e99fdSEd Maste event_assign(&ev, base, fd, EV_READ, callback, &ev); 111*c43e99fdSEd Maste 112*c43e99fdSEd Maste In other words, there was no easy way for event_new() to set up an 113*c43e99fdSEd Maste event so that the event itself would be its callback argument. 114*c43e99fdSEd Maste Libevent 2.1 lets you do this by passing "event_self_cbarg()" as the 115*c43e99fdSEd Maste callback argument: 116*c43e99fdSEd Maste 117*c43e99fdSEd Maste struct event *evp; 118*c43e99fdSEd Maste evp = event_new(base, fd, EV_READ, callback, 119*c43e99fdSEd Maste event_self_cbarg()); 120*c43e99fdSEd Maste 121*c43e99fdSEd Maste There's also a new event_base_get_running_event() function you can 122*c43e99fdSEd Maste call from within a Libevent callback to get a pointer to the current 123*c43e99fdSEd Maste event. This should never be strictly necessary, but it's sometimes 124*c43e99fdSEd Maste convenient. 125*c43e99fdSEd Maste 126*c43e99fdSEd Maste The event_base_once() function used to leak some memory if the event 127*c43e99fdSEd Maste that it added was never actually triggered. Now, its memory is 128*c43e99fdSEd Maste tracked in the event_base and freed when the event_base is freed. 129*c43e99fdSEd Maste Note however that Libevent doesn't know how to free any information 130*c43e99fdSEd Maste passed as the callback argument to event_base_once is still something 131*c43e99fdSEd Maste you'll might need a way to de-allocate yourself. 132*c43e99fdSEd Maste 133*c43e99fdSEd Maste There is an event_get_priority() function to return an event's 134*c43e99fdSEd Maste priority. 135*c43e99fdSEd Maste 136*c43e99fdSEd Maste By analogy to event_base_loopbreak(), there is now an 137*c43e99fdSEd Maste event_base_loopcontinue() that tells Libevent to stop processing 138*c43e99fdSEd Maste active event callbacks, and re-scan for new events right away. 139*c43e99fdSEd Maste 140*c43e99fdSEd Maste There's a function, event_base_foreach_event(), that can iterate over 141*c43e99fdSEd Maste every event currently pending or active on an event base, and invoke a 142*c43e99fdSEd Maste user-supplied callback on each. The callback must not alter the events 143*c43e99fdSEd Maste or add or remove anything to the event base. 144*c43e99fdSEd Maste 145*c43e99fdSEd Maste We now have an event_remove_timer() function to remove the timeout on 146*c43e99fdSEd Maste an event while leaving its socket and/or signal triggers unchanged. 147*c43e99fdSEd Maste (If we were designing the API from scratch, this would be the behavior 148*c43e99fdSEd Maste of "event_add(ev, NULL)" on an already-added event with a timeout. But 149*c43e99fdSEd Maste that's a no-op in past versions of Libevent, and we don't want to 150*c43e99fdSEd Maste break compatibility.) 151*c43e99fdSEd Maste 152*c43e99fdSEd Maste You can use the new event_base_get_num_events() function to find the 153*c43e99fdSEd Maste number of events active or pending on an event_base. To find the 154*c43e99fdSEd Maste largest number of events that there have been since the last call, use 155*c43e99fdSEd Maste event_base_get_max_events(). 156*c43e99fdSEd Maste 157*c43e99fdSEd Maste You can now activate all the events waiting for a given fd or signal 158*c43e99fdSEd Maste using the event_base_active_by_fd() and event_base_active_by_signal() 159*c43e99fdSEd Maste APIs. 160*c43e99fdSEd Maste 161*c43e99fdSEd Maste On backends that support it (currently epoll), there is now an 162*c43e99fdSEd Maste EV_CLOSED flag that programs can use to detect when a socket has 163*c43e99fdSEd Maste closed without having to read all the bytes until receiving an EOF. 164*c43e99fdSEd Maste 165*c43e99fdSEd Maste1.3. Event finalization 166*c43e99fdSEd Maste 167*c43e99fdSEd Maste1.3.1. Why event finalization? 168*c43e99fdSEd Maste 169*c43e99fdSEd Maste Libevent 2.1 now supports an API for safely "finalizing" events that 170*c43e99fdSEd Maste might be running in multiple threads, and provides a way to slightly 171*c43e99fdSEd Maste change the semantics of event_del() to prevent deadlocks in 172*c43e99fdSEd Maste multithreaded programs. 173*c43e99fdSEd Maste 174*c43e99fdSEd Maste To motivate this feature, consider the following code, in the context 175*c43e99fdSEd Maste of a mulithreaded Libevent application: 176*c43e99fdSEd Maste 177*c43e99fdSEd Maste struct connection *conn = event_get_callback_arg(ev); 178*c43e99fdSEd Maste event_del(ev); 179*c43e99fdSEd Maste connection_free(conn); 180*c43e99fdSEd Maste 181*c43e99fdSEd Maste Suppose that the event's callback might be running in another thread, 182*c43e99fdSEd Maste and using the value of "conn" concurrently. We wouldn't want to 183*c43e99fdSEd Maste execute the connection_free() call until "conn" is no longer in use. 184*c43e99fdSEd Maste How can we make this code safe? 185*c43e99fdSEd Maste 186*c43e99fdSEd Maste Libevent 2.0 answered that question by saying that the event_del() 187*c43e99fdSEd Maste call should block if the event's callback is running in another 188*c43e99fdSEd Maste thread. That way, we can be sure that event_del() has canceled the 189*c43e99fdSEd Maste callback (if the callback hadn't started running yet), or has waited 190*c43e99fdSEd Maste for the callback to finish. 191*c43e99fdSEd Maste 192*c43e99fdSEd Maste But now suppose that the data structure is protected by a lock, and we 193*c43e99fdSEd Maste have the following code: 194*c43e99fdSEd Maste 195*c43e99fdSEd Maste void check_disable(struct connection *connection) { 196*c43e99fdSEd Maste lock(connection); 197*c43e99fdSEd Maste if (should_stop_reading(connection)) 198*c43e99fdSEd Maste event_del(connection->read_event); 199*c43e99fdSEd Maste unlock(connection); 200*c43e99fdSEd Maste } 201*c43e99fdSEd Maste 202*c43e99fdSEd Maste What happens when we call check_disable() from a callback and from 203*c43e99fdSEd Maste another thread? Let's say that the other thread gets the lock 204*c43e99fdSEd Maste first. If it decides to call event_del(), it will wait for the 205*c43e99fdSEd Maste callback to finish. But meanwhile, the callback will be waiting for 206*c43e99fdSEd Maste the lock on the connection. Since each threads is waiting for the 207*c43e99fdSEd Maste other one to release a resource, the program will deadlock. 208*c43e99fdSEd Maste 209*c43e99fdSEd Maste This bug showed up in multithreaded bufferevent programs in 2.1, 210*c43e99fdSEd Maste particularly when freeing bufferevents. (For more information, see 211*c43e99fdSEd Maste the "Deadlock when calling bufferevent_free from an other thread" 212*c43e99fdSEd Maste thread on libevent-users starting on 6 August 2012 and running through 213*c43e99fdSEd Maste February of 2013. You might also like to read my earlier writeup at 214*c43e99fdSEd Maste http://archives.seul.org/libevent/users/Feb-2012/msg00053.html and 215*c43e99fdSEd Maste the ensuing discussion.) 216*c43e99fdSEd Maste 217*c43e99fdSEd Maste1.3.2. The EV_FINALIZE flag and avoiding deadlock 218*c43e99fdSEd Maste 219*c43e99fdSEd Maste To prevent the deadlock condition described above, Libevent 220*c43e99fdSEd Maste 2.1.3-alpha adds a new flag, "EV_FINALIZE". You can pass it to 221*c43e99fdSEd Maste event_new() and event_assign() along with EV_READ, EV_WRITE, and the 222*c43e99fdSEd Maste other event flags. 223*c43e99fdSEd Maste 224*c43e99fdSEd Maste When an event is constructed with the EV_FINALIZE flag, event_del() 225*c43e99fdSEd Maste will not block on that event, even when the event's callback is 226*c43e99fdSEd Maste running in another thread. By using EV_FINALIZE, you are therefore 227*c43e99fdSEd Maste promising not to use the "event_del(ev); free(event_get_callback_arg(ev));" 228*c43e99fdSEd Maste pattern, but rather to use one of the finalization functions below to 229*c43e99fdSEd Maste clean up the event. 230*c43e99fdSEd Maste 231*c43e99fdSEd Maste EV_FINALIZE has no effect on a single-threaded program, or on a 232*c43e99fdSEd Maste program where events are only used from one thread. 233*c43e99fdSEd Maste 234*c43e99fdSEd Maste 235*c43e99fdSEd Maste There are also two new variants of event_del() that you can use for 236*c43e99fdSEd Maste more fine-grained control: 237*c43e99fdSEd Maste event_del_noblock(ev) 238*c43e99fdSEd Maste event_del_block(ev) 239*c43e99fdSEd Maste The event_del_noblock() function will never block, even if the event 240*c43e99fdSEd Maste callback is running in another thread and doesn't have the EV_FINALIZE 241*c43e99fdSEd Maste flag. The event_del_block() function will _always_ block if the event 242*c43e99fdSEd Maste callback is running in another thread, even if the event _does_ have 243*c43e99fdSEd Maste the EV_FINALIZE flag. 244*c43e99fdSEd Maste 245*c43e99fdSEd Maste [A future version of Libevent may have a way to make the EV_FINALIZE 246*c43e99fdSEd Maste flag the default.] 247*c43e99fdSEd Maste 248*c43e99fdSEd Maste1.3.3. Safely finalizing events 249*c43e99fdSEd Maste 250*c43e99fdSEd Maste To safely tear down an event that may be running, Libevent 2.1.3-alpha 251*c43e99fdSEd Maste introduces event_finalize() and event_free_finalize(). You call them 252*c43e99fdSEd Maste on an event, and provide a finalizer callback to be run on the event 253*c43e99fdSEd Maste and its callback argument once the event is definitely no longer 254*c43e99fdSEd Maste running. 255*c43e99fdSEd Maste 256*c43e99fdSEd Maste With event_free_finalize(), the event is also freed once the finalizer 257*c43e99fdSEd Maste callback has been invoked. 258*c43e99fdSEd Maste 259*c43e99fdSEd Maste A finalized event cannot be re-added or activated. The finalizer 260*c43e99fdSEd Maste callback must not add events, activate events, or attempt to 261*c43e99fdSEd Maste "resucitate" the event being finalized in any way. 262*c43e99fdSEd Maste 263*c43e99fdSEd Maste If any finalizer callbacks are pending as the event_base is being 264*c43e99fdSEd Maste freed, they will be invoked. You can override this behavior with the 265*c43e99fdSEd Maste new function event_base_free_nofinalize(). 266*c43e99fdSEd Maste 267*c43e99fdSEd Maste1.4. New debugging features 268*c43e99fdSEd Maste 269*c43e99fdSEd Maste You can now turn on debug logs at runtime using a new function, 270*c43e99fdSEd Maste event_enable_debug_logging(). 271*c43e99fdSEd Maste 272*c43e99fdSEd Maste The event_enable_lock_debugging() function is now spelled correctly. 273*c43e99fdSEd Maste You can still use the old "event_enable_lock_debuging" name, though, 274*c43e99fdSEd Maste so your old programs shouldnt' break. 275*c43e99fdSEd Maste 276*c43e99fdSEd Maste There's also been some work done to try to make the debugging logs 277*c43e99fdSEd Maste more generally useful. 278*c43e99fdSEd Maste 279*c43e99fdSEd Maste1.5. New evbuffer functions 280*c43e99fdSEd Maste 281*c43e99fdSEd Maste In Libevent 2.0, we introduced evbuffer_add_file() to add an entire 282*c43e99fdSEd Maste file's contents to an evbuffer, and then send them using sendfile() or 283*c43e99fdSEd Maste mmap() as appropriate. This API had some drawbacks, however. 284*c43e99fdSEd Maste Notably, it created one mapping or fd for every instance of the same 285*c43e99fdSEd Maste file added to any evbuffer. Also, adding a file to an evbuffer could 286*c43e99fdSEd Maste make that buffer unusable with SSL bufferevents, filtering 287*c43e99fdSEd Maste bufferevents, and any code that tried to read the contents of the 288*c43e99fdSEd Maste evbuffer. 289*c43e99fdSEd Maste 290*c43e99fdSEd Maste Libevent 2.1 adds a new evbuffer_file_segment API to solve these 291*c43e99fdSEd Maste problems. Now, you can use evbuffer_file_segment_new() to construct a 292*c43e99fdSEd Maste file-segment object, and evbuffer_add_file_segment() to insert it (or 293*c43e99fdSEd Maste part of it) into an evbuffer. These segments avoid creating redundant 294*c43e99fdSEd Maste maps or fds. Better still, the code is smart enough (when the OS 295*c43e99fdSEd Maste supports sendfile) to map the file when that's necessary, and use 296*c43e99fdSEd Maste sendfile() otherwise. 297*c43e99fdSEd Maste 298*c43e99fdSEd Maste File segments can receive callback functions that are invoked when the 299*c43e99fdSEd Maste file segments are freed. 300*c43e99fdSEd Maste 301*c43e99fdSEd Maste The evbuffer_ptr interface has been extended so that an evbuffer_ptr 302*c43e99fdSEd Maste can now yield a point just after the end of the buffer. This makes 303*c43e99fdSEd Maste many algorithms simpler to implement. 304*c43e99fdSEd Maste 305*c43e99fdSEd Maste There's a new evbuffer_add_buffer() interface that you can use to add 306*c43e99fdSEd Maste one buffer to another nondestructively. When you say 307*c43e99fdSEd Maste evbuffer_add_buffer_reference(outbuf, inbuf), outbuf now contains a 308*c43e99fdSEd Maste reference to the contents of inbuf. 309*c43e99fdSEd Maste 310*c43e99fdSEd Maste To aid in adding data in bulk while minimizing evbuffer calls, there 311*c43e99fdSEd Maste is an evbuffer_add_iovec() function. 312*c43e99fdSEd Maste 313*c43e99fdSEd Maste There's a new evbuffer_copyout_from() variant function to enable 314*c43e99fdSEd Maste copying data nondestructively from the middle of a buffer. 315*c43e99fdSEd Maste 316*c43e99fdSEd Maste evbuffer_readln() now supports an EVBUFFER_EOL_NUL argument to fetch 317*c43e99fdSEd Maste NUL-terminated strings from buffers. 318*c43e99fdSEd Maste 319*c43e99fdSEd Maste There's a new evbuffer_set_flags()/evbuffer_clear_flags() that you can use to 320*c43e99fdSEd Maste set EVBUFFER_FLAG_DRAINS_TO_FD. 321*c43e99fdSEd Maste 322*c43e99fdSEd Maste1.6. New functions and features: bufferevents 323*c43e99fdSEd Maste 324*c43e99fdSEd Maste You can now use the bufferevent_getcb() function to find out a 325*c43e99fdSEd Maste bufferevent's callbacks. Previously, there was no supported way to do 326*c43e99fdSEd Maste that. 327*c43e99fdSEd Maste 328*c43e99fdSEd Maste The largest chunk readable or writeable in a single bufferevent 329*c43e99fdSEd Maste callback is no longer hardcoded; it's now configurable with 330*c43e99fdSEd Maste the new functions bufferevent_set_max_single_read() and 331*c43e99fdSEd Maste bufferevent_set_max_single_write(). 332*c43e99fdSEd Maste 333*c43e99fdSEd Maste For consistency, OpenSSL bufferevents now make sure to always set one 334*c43e99fdSEd Maste of BEV_EVENT_READING or BEV_EVENT_WRITING when invoking an event 335*c43e99fdSEd Maste callback. 336*c43e99fdSEd Maste 337*c43e99fdSEd Maste Calling bufferevent_set_timeouts(bev, NULL, NULL) now removes the 338*c43e99fdSEd Maste timeouts from socket and ssl bufferevents correctly. 339*c43e99fdSEd Maste 340*c43e99fdSEd Maste You can find the priority at which a bufferevent runs with 341*c43e99fdSEd Maste bufferevent_get_priority(). 342*c43e99fdSEd Maste 343*c43e99fdSEd Maste The function bufferevent_get_token_bucket_cfg() can retrieve the 344*c43e99fdSEd Maste rate-limit settings for a bufferevent; bufferevent_getwatermark() can 345*c43e99fdSEd Maste return a bufferevent's current watermark settings. 346*c43e99fdSEd Maste 347*c43e99fdSEd Maste You can manually trigger a bufferevent's callbacks via 348*c43e99fdSEd Maste bufferevent_trigger() and bufferevent_trigger_event(). 349*c43e99fdSEd Maste 350*c43e99fdSEd Maste Also you can manually increment/decrement reference for bufferevent with 351*c43e99fdSEd Maste bufferevent_incref()/bufferevent_decref(), it is useful in situations where a 352*c43e99fdSEd Maste user may reference the bufferevent somewhere else. 353*c43e99fdSEd Maste 354*c43e99fdSEd Maste Now bufferevent_openssl supports "dirty" shutdown (when the peer closes the 355*c43e99fdSEd Maste TCP connection before closing the SSL channel), see 356*c43e99fdSEd Maste bufferevent_openssl_get_allow_dirty_shutdown() and 357*c43e99fdSEd Maste bufferevent_openssl_set_allow_dirty_shutdown(). 358*c43e99fdSEd Maste 359*c43e99fdSEd Maste And also libevent supports openssl 1.1. 360*c43e99fdSEd Maste 361*c43e99fdSEd Maste1.7. New functions and features: evdns 362*c43e99fdSEd Maste 363*c43e99fdSEd Maste The previous evdns interface used an "open a test UDP socket" trick in 364*c43e99fdSEd Maste order to detect IPv6 support. This was a hack, since it would 365*c43e99fdSEd Maste sometimes badly confuse people's firewall software, even though no 366*c43e99fdSEd Maste packets were sent. The current evdns interface-detection code uses 367*c43e99fdSEd Maste the appropriate OS functions to see which interfaces are configured. 368*c43e99fdSEd Maste 369*c43e99fdSEd Maste The evdns_base_new() function now has multiple possible values for its 370*c43e99fdSEd Maste second (flags) argument. Using 1 and 0 have their old meanings, though the 371*c43e99fdSEd Maste 1 flag now has a symbolic name of EVDNS_BASE_INITIALIZE_NAMESERVERS. 372*c43e99fdSEd Maste A second flag is now supported too: the EVDNS_BASE_DISABLE_WHEN_INACTIVE 373*c43e99fdSEd Maste flag, which tells the evdns_base that it should not prevent Libevent from 374*c43e99fdSEd Maste exiting while it has no DNS requests in progress. 375*c43e99fdSEd Maste 376*c43e99fdSEd Maste There is a new evdns_base_clear_host_addresses() function to remove 377*c43e99fdSEd Maste all the /etc/hosts addresses registered with an evdns instance. 378*c43e99fdSEd Maste 379*c43e99fdSEd Maste Also there is evdns_base_get_nameserver_addr() for retrieve the address of 380*c43e99fdSEd Maste the 'idx'th configured nameserver. 381*c43e99fdSEd Maste 382*c43e99fdSEd Maste1.8. New functions and features: evconnlistener 383*c43e99fdSEd Maste 384*c43e99fdSEd Maste Libevent 2.1 adds the following evconnlistener flags: 385*c43e99fdSEd Maste 386*c43e99fdSEd Maste LEV_OPT_DEFERRED_ACCEPT -- Tells the OS that it doesn't need to 387*c43e99fdSEd Maste report sockets as having arrived until the initiator has sent some 388*c43e99fdSEd Maste data too. This can greatly improve performance with protocols like 389*c43e99fdSEd Maste HTTP where the client always speaks first. On operating systems 390*c43e99fdSEd Maste that don't support this functionality, this option has no effect. 391*c43e99fdSEd Maste 392*c43e99fdSEd Maste LEV_OPT_REUSEABLE_PORT -- Indicates that we ask to allow multiple servers 393*c43e99fdSEd Maste to bind to the same port if they each set the option Ionly on Linux and 394*c43e99fdSEd Maste >=3.9) 395*c43e99fdSEd Maste 396*c43e99fdSEd Maste LEV_OPT_DISABLED -- Creates an evconnlistener in the disabled (not 397*c43e99fdSEd Maste listening) state. 398*c43e99fdSEd Maste 399*c43e99fdSEd Maste Libevent 2.1 changes the behavior of the LEV_OPT_CLOSE_ON_EXEC 400*c43e99fdSEd Maste flag. Previously, it would apply to the listener sockets, but not to 401*c43e99fdSEd Maste the accepted sockets themselves. That's almost never what you want. 402*c43e99fdSEd Maste Now, it applies both to the listener and the accepted sockets. 403*c43e99fdSEd Maste 404*c43e99fdSEd Maste1.9. New functions and features: evhttp 405*c43e99fdSEd Maste 406*c43e99fdSEd Maste ********************************************************************** 407*c43e99fdSEd Maste NOTE: The evhttp module will eventually be deprecated in favor of Mark 408*c43e99fdSEd Maste Ellzey's libevhtp library. Don't worry -- this won't happen until 409*c43e99fdSEd Maste libevhtp provides every feature that evhttp does, and provides a 410*c43e99fdSEd Maste compatible interface that applications can use to migrate. 411*c43e99fdSEd Maste ********************************************************************** 412*c43e99fdSEd Maste 413*c43e99fdSEd Maste Previously, you could only set evhttp timeouts in increments of one 414*c43e99fdSEd Maste second. Now, you can use evhttp_set_timeout_tv() and 415*c43e99fdSEd Maste evhttp_connection_set_timeout_tv() to configure 416*c43e99fdSEd Maste microsecond-granularity timeouts. 417*c43e99fdSEd Maste 418*c43e99fdSEd Maste Also there is evhttp_connection_set_initial_retry_tv() to change initial 419*c43e99fdSEd Maste retry timeout. 420*c43e99fdSEd Maste 421*c43e99fdSEd Maste There are a new pair of functions: evhttp_set_bevcb() and 422*c43e99fdSEd Maste evhttp_connection_base_bufferevent_new(), that you can use to 423*c43e99fdSEd Maste configure which bufferevents will be used for incoming and outgoing 424*c43e99fdSEd Maste http connections respectively. These functions, combined with SSL 425*c43e99fdSEd Maste bufferevents, should enable HTTPS support. 426*c43e99fdSEd Maste 427*c43e99fdSEd Maste There's a new evhttp_foreach_bound_socket() function to iterate over 428*c43e99fdSEd Maste every listener on an evhttp object. 429*c43e99fdSEd Maste 430*c43e99fdSEd Maste Whitespace between lines in headers is now folded into a single space; 431*c43e99fdSEd Maste whitespace at the end of a header is now removed. 432*c43e99fdSEd Maste 433*c43e99fdSEd Maste The socket errno value is now preserved when invoking an http error 434*c43e99fdSEd Maste callback. 435*c43e99fdSEd Maste 436*c43e99fdSEd Maste There's a new kind of request callback for errors; you can set it with 437*c43e99fdSEd Maste evhttp_request_set_error_cb(). It gets called when there's a request error, 438*c43e99fdSEd Maste and actually reports the error code and lets you figure out which request 439*c43e99fdSEd Maste failed. 440*c43e99fdSEd Maste 441*c43e99fdSEd Maste You can navigate from an evhttp_connection back to its evhttp with the 442*c43e99fdSEd Maste new evhttp_connection_get_server() function. 443*c43e99fdSEd Maste 444*c43e99fdSEd Maste You can override the default HTTP Content-Type with the new 445*c43e99fdSEd Maste evhttp_set_default_content_type() function 446*c43e99fdSEd Maste 447*c43e99fdSEd Maste There's a new evhttp_connection_get_addr() API to return the peer 448*c43e99fdSEd Maste address of an evhttp_connection. 449*c43e99fdSEd Maste 450*c43e99fdSEd Maste The new evhttp_send_reply_chunk_with_cb() is a variant of 451*c43e99fdSEd Maste evhttp_send_reply_chunk() with a callback to be invoked when the 452*c43e99fdSEd Maste chunk is sent. 453*c43e99fdSEd Maste 454*c43e99fdSEd Maste The evhttp_request_set_header_cb() facility adds a callback to be 455*c43e99fdSEd Maste invoked while parsing headers. 456*c43e99fdSEd Maste 457*c43e99fdSEd Maste The evhttp_request_set_on_complete_cb() facility adds a callback to be 458*c43e99fdSEd Maste invoked on request completion. 459*c43e99fdSEd Maste 460*c43e99fdSEd Maste You can add linger-close for http server by passing 461*c43e99fdSEd Maste EVHTTP_SERVER_LINGERING_CLOSE to evhttp_set_flags(), with this flag server 462*c43e99fdSEd Maste read all the clients body, and only after this respond with an error if the 463*c43e99fdSEd Maste clients body exceed max_body_size (since some clients cannot read response 464*c43e99fdSEd Maste otherwise). 465*c43e99fdSEd Maste 466*c43e99fdSEd Maste The evhttp_connection_set_family() can bypass family hint to evdns. 467*c43e99fdSEd Maste 468*c43e99fdSEd Maste There are some flags available for connections, which can be installed with 469*c43e99fdSEd Maste evhttp_connection_set_flags(): 470*c43e99fdSEd Maste - EVHTTP_CON_REUSE_CONNECTED_ADDR -- reuse connection address on retry (avoid 471*c43e99fdSEd Maste extra DNS request). 472*c43e99fdSEd Maste - EVHTTP_CON_READ_ON_WRITE_ERROR - try read error, since server may already 473*c43e99fdSEd Maste close the connection. 474*c43e99fdSEd Maste 475*c43e99fdSEd Maste The evhttp_connection_free_on_completion() can be used to tell libevent to 476*c43e99fdSEd Maste free the connection object after the last request has completed or failed. 477*c43e99fdSEd Maste 478*c43e99fdSEd Maste There is evhttp_request_get_response_code_line() if 479*c43e99fdSEd Maste evhttp_request_get_response_code() is not enough for you. 480*c43e99fdSEd Maste 481*c43e99fdSEd Maste There are *evhttp_uri_parse_with_flags() that accepts 482*c43e99fdSEd Maste EVHTTP_URI_NONCONFORMANT to tolerate URIs that do not conform to RFC3986. 483*c43e99fdSEd Maste The evhttp_uri_set_flags() can changes the flags on URI. 484*c43e99fdSEd Maste 485*c43e99fdSEd Maste1.10. New functions and features: evutil 486*c43e99fdSEd Maste 487*c43e99fdSEd Maste There's a function "evutil_secure_rng_set_urandom_device_file()" that 488*c43e99fdSEd Maste you can use to override the default file that Libevent uses to seed 489*c43e99fdSEd Maste its (sort-of) secure RNG. 490*c43e99fdSEd Maste 491*c43e99fdSEd Maste The evutil_date_rfc1123() returns date in RFC1123 492*c43e99fdSEd Maste 493*c43e99fdSEd Maste There are new API to work with monotonic timer -- monotonic time is 494*c43e99fdSEd Maste guaranteed never to run in reverse, but is not necessarily epoch-based. Use 495*c43e99fdSEd Maste it to make reliable measurements of elapsed time between events even when the 496*c43e99fdSEd Maste system time may be changed: 497*c43e99fdSEd Maste - evutil_monotonic_timer_new()/evutil_monotonic_timer_free() 498*c43e99fdSEd Maste - evutil_configure_monotonic_time() 499*c43e99fdSEd Maste - evutil_gettime_monotonic() 500*c43e99fdSEd Maste 501*c43e99fdSEd Maste Use evutil_make_listen_socket_reuseable_port() to set SO_REUSEPORT (linux >= 502*c43e99fdSEd Maste 3.9) 503*c43e99fdSEd Maste 504*c43e99fdSEd Maste The evutil_make_tcp_listen_socket_deferred() can make a tcp listener socket 505*c43e99fdSEd Maste defer accept()s until there is data to read (TCP_DEFER_ACCEPT). 506*c43e99fdSEd Maste 507*c43e99fdSEd Maste2. Cross-platform performance improvements 508*c43e99fdSEd Maste 509*c43e99fdSEd Maste2.1. Better data structures 510*c43e99fdSEd Maste 511*c43e99fdSEd Maste We replaced several users of the sys/queue.h "TAILQ" data structure 512*c43e99fdSEd Maste with the "LIST" data structure. Because this data type doesn't 513*c43e99fdSEd Maste require FIFO access, it requires fewer pointer checks and 514*c43e99fdSEd Maste manipulations to keep it in line. 515*c43e99fdSEd Maste 516*c43e99fdSEd Maste All previous versions of Libevent have kept every pending (added) 517*c43e99fdSEd Maste event in an "eventqueue" data structure. Starting in Libevent 2.0, 518*c43e99fdSEd Maste however, this structure became redundant: every pending timeout event 519*c43e99fdSEd Maste is stored in the timeout heap or in one of the common_timeout queues, 520*c43e99fdSEd Maste and every pending fd or signal event is stored in an evmap. Libevent 521*c43e99fdSEd Maste 2.1 removes this data structure, and thereby saves all of the code 522*c43e99fdSEd Maste that we'd been using to keep it updated. 523*c43e99fdSEd Maste 524*c43e99fdSEd Maste2.2. Faster activations and timeouts 525*c43e99fdSEd Maste 526*c43e99fdSEd Maste It's a common pattern in older code to use event_base_once() with a 527*c43e99fdSEd Maste 0-second timeout to ensure that a callback will get run 'as soon as 528*c43e99fdSEd Maste possible' in the current iteration of the Libevent loop. We optimize 529*c43e99fdSEd Maste this case by calling event_active() directly, and bypassing the 530*c43e99fdSEd Maste timeout pool. (People who are using this pattern should also consider 531*c43e99fdSEd Maste using event_active() themselves.) 532*c43e99fdSEd Maste 533*c43e99fdSEd Maste Libevent 2.0 would wake up a polling event loop whenever the first 534*c43e99fdSEd Maste timeout in the event loop was adjusted--whether it had become earlier 535*c43e99fdSEd Maste or later. We now only notify the event loop when a change causes the 536*c43e99fdSEd Maste expiration time to become _sooner_ than it would have been otherwise. 537*c43e99fdSEd Maste 538*c43e99fdSEd Maste The timeout heap code is now optimized to perform fewer comparisons 539*c43e99fdSEd Maste and shifts when changing or removing a timeout. 540*c43e99fdSEd Maste 541*c43e99fdSEd Maste Instead of checking for a wall-clock time jump every time we call 542*c43e99fdSEd Maste clock_gettime(), we now check only every 5 seconds. This should save 543*c43e99fdSEd Maste a huge number of gettimeofday() calls. 544*c43e99fdSEd Maste 545*c43e99fdSEd Maste2.3. Microoptimizations 546*c43e99fdSEd Maste 547*c43e99fdSEd Maste Internal event list maintainance no longer use the antipattern where 548*c43e99fdSEd Maste we have one function with multiple totally independent behaviors 549*c43e99fdSEd Maste depending on an argument: 550*c43e99fdSEd Maste #define OP1 1 551*c43e99fdSEd Maste #define OP2 2 552*c43e99fdSEd Maste #define OP3 3 553*c43e99fdSEd Maste void func(int operation, struct event *ev) { 554*c43e99fdSEd Maste switch (op) { 555*c43e99fdSEd Maste ... 556*c43e99fdSEd Maste } 557*c43e99fdSEd Maste } 558*c43e99fdSEd Maste Instead, these functions are now split into separate functions for 559*c43e99fdSEd Maste each operation: 560*c43e99fdSEd Maste void func_op1(struct event *ev) { ... } 561*c43e99fdSEd Maste void func_op2(struct event *ev) { ... } 562*c43e99fdSEd Maste void func_op3(struct event *ev) { ... } 563*c43e99fdSEd Maste 564*c43e99fdSEd Maste This produces better code generation and inlining decisions on some 565*c43e99fdSEd Maste compilers, and makes the code easier to read and check. 566*c43e99fdSEd Maste 567*c43e99fdSEd Maste2.4. Evbuffer performance improvements 568*c43e99fdSEd Maste 569*c43e99fdSEd Maste The EVBUFFER_EOL_CRLF line-ending type is now much faster, thanks to 570*c43e99fdSEd Maste smart optimizations. 571*c43e99fdSEd Maste 572*c43e99fdSEd Maste2.5. HTTP performance improvements 573*c43e99fdSEd Maste 574*c43e99fdSEd Maste o Performance tweak to evhttp_parse_request_line. (aee1a97 Mark Ellzey) 575*c43e99fdSEd Maste o Add missing break to evhttp_parse_request_line (0fcc536) 576*c43e99fdSEd Maste 577*c43e99fdSEd Maste2.6. Coarse timers by default on Linux 578*c43e99fdSEd Maste 579*c43e99fdSEd Maste Due to limitations of the epoll interface, Libevent programs using epoll 580*c43e99fdSEd Maste have not previously been able to wait for timeouts with accuracy smaller 581*c43e99fdSEd Maste than 1 millisecond. But Libevent had been using CLOCK_MONOTONIC for 582*c43e99fdSEd Maste timekeeping on Linux, which is needlessly expensive: CLOCK_MONOTONIC_COARSE 583*c43e99fdSEd Maste has approximately the resolution corresponding to epoll, and is much faster 584*c43e99fdSEd Maste to invoke than CLOCK_MONOTONIC. 585*c43e99fdSEd Maste 586*c43e99fdSEd Maste To disable coarse timers, and get a more plausible precision, use the 587*c43e99fdSEd Maste new EVENT_BASE_FLAG_PRECISE_TIMER flag when setting up your event base. 588*c43e99fdSEd Maste 589*c43e99fdSEd Maste3. Backend/OS-specific improvements 590*c43e99fdSEd Maste 591*c43e99fdSEd Maste3.1. Linux-specific improvements 592*c43e99fdSEd Maste 593*c43e99fdSEd Maste The logic for deciding which arguements to use with epoll_ctl() is now 594*c43e99fdSEd Maste a table-driven lookup, rather than the previous pile of cascading 595*c43e99fdSEd Maste branches. This should minimize epoll_ctl() calls and make the epoll 596*c43e99fdSEd Maste code run a little faster on change-heavy loads. 597*c43e99fdSEd Maste 598*c43e99fdSEd Maste Libevent now takes advantage of Linux's support for enhanced APIs 599*c43e99fdSEd Maste (e.g., SOCK_CLOEXEC, SOCK_NONBLOCK, accept4, pipe2) that allow us to 600*c43e99fdSEd Maste simultaneously create a socket, make it nonblocking, and make it 601*c43e99fdSEd Maste close-on-exec. This should save syscalls throughout our codebase, and 602*c43e99fdSEd Maste avoid race-conditions if an exec() occurs after a socket is socket is 603*c43e99fdSEd Maste created but before we can make it close-on-execute on it. 604*c43e99fdSEd Maste 605*c43e99fdSEd Maste3.2. Windows-specific improvements 606*c43e99fdSEd Maste 607*c43e99fdSEd Maste We now use GetSystemTimeAsFileTime to implement gettimeofday. It's 608*c43e99fdSEd Maste significantly faster and more accurate than our old ftime()-based approach. 609*c43e99fdSEd Maste 610*c43e99fdSEd Maste3.3. Improvements in the solaris evport backend. 611*c43e99fdSEd Maste 612*c43e99fdSEd Maste The evport backend has been updated to use many of the infrastructure 613*c43e99fdSEd Maste improvements from Libevent 2.0. Notably, it keeps track of per-fd 614*c43e99fdSEd Maste information using the evmap infrastructure, and removes a number of 615*c43e99fdSEd Maste linear scans over recently-added events. This last change makes it 616*c43e99fdSEd Maste efficient to receive many more events per evport_getn() call, thereby 617*c43e99fdSEd Maste reducing evport overhead in general. 618*c43e99fdSEd Maste 619*c43e99fdSEd Maste3.4. OSX backend improvements 620*c43e99fdSEd Maste 621*c43e99fdSEd Maste The OSX select backend doesn't like to have more than a certain number 622*c43e99fdSEd Maste of fds set unless an "unlimited select" option has been set. 623*c43e99fdSEd Maste Therefore, we now set it. 624*c43e99fdSEd Maste 625*c43e99fdSEd Maste3.5. Monotonic clocks on even more platforms 626*c43e99fdSEd Maste 627*c43e99fdSEd Maste Libevent previously used a monotonic clock for its internal timekeeping 628*c43e99fdSEd Maste only on platforms supporting the POSIX clock_gettime() interface. Now, 629*c43e99fdSEd Maste Libevent has support for monotonic clocks on OSX and Windows too, and a 630*c43e99fdSEd Maste fallback implementation for systems without monotonic clocks that will at 631*c43e99fdSEd Maste least keep time running forwards. 632*c43e99fdSEd Maste 633*c43e99fdSEd Maste Using monotonic timers makes Libevent more resilient to changes in the 634*c43e99fdSEd Maste system time, as can happen in small amounts due to clock adjustments from 635*c43e99fdSEd Maste NTP, or in large amounts due to users who move their system clocks all over 636*c43e99fdSEd Maste the timeline in order to keep nagware from nagging them. 637*c43e99fdSEd Maste 638*c43e99fdSEd Maste3.6. Faster cross-thread notification on kqueue 639*c43e99fdSEd Maste 640*c43e99fdSEd Maste When a thread other than the one in which the main event loop is 641*c43e99fdSEd Maste running needs to wake the thread running the main event loop, Libevent 642*c43e99fdSEd Maste usually writes to a socketpair in order to force the main event loop 643*c43e99fdSEd Maste to wake up. On Linux, we've been able to use eventfd() instead. Now 644*c43e99fdSEd Maste on BSD and OSX systems (any anywhere else that has kqueue with the 645*c43e99fdSEd Maste EVFILT_USER extension), we can use EVFILT_USER to wake up the main 646*c43e99fdSEd Maste thread from kqueue. This should be a tiny bit faster than the 647*c43e99fdSEd Maste previous approach. 648*c43e99fdSEd Maste 649*c43e99fdSEd Maste4. Infrastructure improvements 650*c43e99fdSEd Maste 651*c43e99fdSEd Maste4.1. Faster tests 652*c43e99fdSEd Maste 653*c43e99fdSEd Maste I've spent some time to try to make the unit tests run faster in 654*c43e99fdSEd Maste Libevent 2.1. Nearly all of this was a matter of searching slow tests 655*c43e99fdSEd Maste for unreasonably long timeouts, and cutting them down to reasonably 656*c43e99fdSEd Maste long delays, though on one or two cases I actually had to parallelize 657*c43e99fdSEd Maste an operation or improve an algorithm. 658*c43e99fdSEd Maste 659*c43e99fdSEd Maste On my desktop, a full "make verify" run of Libevent 2.0.18-stable 660*c43e99fdSEd Maste requires about 218 seconds. Libevent 2.1.1-alpha cuts this down to 661*c43e99fdSEd Maste about 78 seconds. 662*c43e99fdSEd Maste 663*c43e99fdSEd Maste Faster unit tests are great, since they let programmers test their 664*c43e99fdSEd Maste changes without losing their train of thought. 665*c43e99fdSEd Maste 666*c43e99fdSEd Maste4.2. Finicky tests are now off-by-default 667*c43e99fdSEd Maste 668*c43e99fdSEd Maste The Tinytest unit testing framework now supports optional tests, and 669*c43e99fdSEd Maste Libevent uses them. By default, Libevent's unit testing framework 670*c43e99fdSEd Maste does not run tests that require a working network, and does not run 671*c43e99fdSEd Maste tests that tend to fail on heavily loaded systems because of timing 672*c43e99fdSEd Maste issues. To re-enable all tests, run ./test/regress using the "@all" 673*c43e99fdSEd Maste alias. 674*c43e99fdSEd Maste 675*c43e99fdSEd Maste4.3. Modernized use of autotools 676*c43e99fdSEd Maste 677*c43e99fdSEd Maste Our autotools-based build system has been updated to build without 678*c43e99fdSEd Maste warnings on recent autoconf/automake versions. 679*c43e99fdSEd Maste 680*c43e99fdSEd Maste Libevent's autotools makefiles are no longer recursive. This allows 681*c43e99fdSEd Maste make to use the maximum possible parallelism to do the minimally 682*c43e99fdSEd Maste necessary amount of work. See Peter Miller's "Recursive Make 683*c43e99fdSEd Maste Considered Harmful" at http://miller.emu.id.au/pmiller/books/rmch/ for 684*c43e99fdSEd Maste more information here. 685*c43e99fdSEd Maste 686*c43e99fdSEd Maste We now use the "quiet build" option to suppress distracting messages 687*c43e99fdSEd Maste about which commandlines are running. You can get them back with 688*c43e99fdSEd Maste "make V=1". 689*c43e99fdSEd Maste 690*c43e99fdSEd Maste4.4. Portability 691*c43e99fdSEd Maste 692*c43e99fdSEd Maste Libevent now uses large-file support internally on platforms where it 693*c43e99fdSEd Maste matters. You shouldn't need to set _LARGEFILE or OFFSET_BITS or 694*c43e99fdSEd Maste anything magic before including the Libevent headers, either, since 695*c43e99fdSEd Maste Libevent now sets the size of ev_off_t to the size of off_t that it 696*c43e99fdSEd Maste received at compile time, not to some (possibly different) size based 697*c43e99fdSEd Maste on current macro definitions when your program is building. 698*c43e99fdSEd Maste 699*c43e99fdSEd Maste We now also use the Autoconf AC_USE_SYSTEM_EXTENSIONS mechanism to 700*c43e99fdSEd Maste enable per-system macros needed to enable not-on-by-default features. 701*c43e99fdSEd Maste Unlike the rest of the autoconf macros, we output these to an 702*c43e99fdSEd Maste internal-use-only evconfig-private.h header, since their names need to 703*c43e99fdSEd Maste survive unmangled. This lets us build correctly on more platforms, 704*c43e99fdSEd Maste and avoid inconsistencies when some files define _GNU_SOURCE and 705*c43e99fdSEd Maste others don't. 706*c43e99fdSEd Maste 707*c43e99fdSEd Maste Libevent now tries to detect OpenSSL via pkg-config. 708*c43e99fdSEd Maste 709*c43e99fdSEd Maste4.5. Standards conformance 710*c43e99fdSEd Maste 711*c43e99fdSEd Maste Previous Libevent versions had no consistent convention for internal 712*c43e99fdSEd Maste vs external identifiers, and used identifiers starting with the "_" 713*c43e99fdSEd Maste character throughout the codebase. That's no good, since the C 714*c43e99fdSEd Maste standard says that identifiers beginning with _ are reserved. I'm not 715*c43e99fdSEd Maste aware of having any collisions with system identifiers, but it's best 716*c43e99fdSEd Maste to fix these things before they cause trouble. 717*c43e99fdSEd Maste 718*c43e99fdSEd Maste We now avoid all use of the _identifiers in the Libevent source code. 719*c43e99fdSEd Maste These changes were made *mainly* through the use of automated scripts, 720*c43e99fdSEd Maste so there shouldn't be any mistakes, but you never know. 721*c43e99fdSEd Maste 722*c43e99fdSEd Maste As an exception, the names _EVENT_LOG_DEBUG, _EVENT_LOG_MSG_, 723*c43e99fdSEd Maste _EVENT_LOG_WARN, and _EVENT_LOG_ERR are still exposed in event.h: they 724*c43e99fdSEd Maste are now deprecated, but to support older code, they will need to stay 725*c43e99fdSEd Maste around for a while. New code should use EVENT_LOG_DEBUG, 726*c43e99fdSEd Maste EVENT_LOG_MSG, EVENT_LOG_WARN, and EVENT_LOG_ERR instead. 727*c43e99fdSEd Maste 728*c43e99fdSEd Maste4.6. Event and callback refactoring 729*c43e99fdSEd Maste 730*c43e99fdSEd Maste As a simplification and optimization to Libevent's "deferred callback" 731*c43e99fdSEd Maste logic (introduced in 2.0 to avoid callback recursion), Libevent now 732*c43e99fdSEd Maste treats all of its deferrable callback types using the same logic it 733*c43e99fdSEd Maste uses for active events. Now deferred events no longer cause priority 734*c43e99fdSEd Maste inversion, no longer require special code to cancel them, and so on. 735*c43e99fdSEd Maste 736*c43e99fdSEd Maste Regular events and deferred callbacks now both descend from an 737*c43e99fdSEd Maste internal light-weight event_callback supertype, and both support 738*c43e99fdSEd Maste priorities and take part in the other anti-priority-inversion 739*c43e99fdSEd Maste mechanisms in Libevent. 740*c43e99fdSEd Maste 741*c43e99fdSEd Maste To avoid starvation from callback recursion (which was the reason we 742*c43e99fdSEd Maste introduced "deferred callbacks" in the first place) the implementation 743*c43e99fdSEd Maste now allows an event callback to be scheduled as "active later": 744*c43e99fdSEd Maste instead of running in the current iteration of the event loop, it runs 745*c43e99fdSEd Maste in the next one. 746*c43e99fdSEd Maste 747*c43e99fdSEd Maste5. Testing 748*c43e99fdSEd Maste 749*c43e99fdSEd Maste Libevent's test coverage level is more or less unchanged since before: 750*c43e99fdSEd Maste we still have over 80% line coverage in our tests on Linux, FreeBSD, NetBSD, 751*c43e99fdSEd Maste Windows, OSX. 752*c43e99fdSEd Maste There are some under-tested modules, though: we need to fix those. 753*c43e99fdSEd Maste 754*c43e99fdSEd Maste And now we have CI: 755*c43e99fdSEd Maste - https://travis-ci.org/libevent/libevent 756*c43e99fdSEd Maste - https://ci.appveyor.com/project/nmathewson/libevent 757*c43e99fdSEd Maste 758*c43e99fdSEd Maste And code coverage: 759*c43e99fdSEd Maste - https://coveralls.io/github/libevent/libevent 760*c43e99fdSEd Maste 761*c43e99fdSEd Maste Plus there is vagrant boxes if you what to test it on more OS'es then 762*c43e99fdSEd Maste travis-ci allows, and there is a wrapper (in python) that will parse logs and 763*c43e99fdSEd Maste provide report: 764*c43e99fdSEd Maste - https://github.com/libevent/libevent-extras/blob/master/tools/vagrant-tests.py 765*c43e99fdSEd Maste 766*c43e99fdSEd Maste6. Contributing 767*c43e99fdSEd Maste 768*c43e99fdSEd Maste From now we have contributing guide and checkpatch.sh. 769