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