libevent-2.1.8-

What's new in Libevent 2.1 Nick Mathewson 0. Before we start 0.1. About this document This document describes the key differences between Libevent 2.0 and Libevent 2.1, from a user's point of view. It's a work in progress. For better documentation about libevent, see the links at http://libevent.org/ Libevent 2.1 would not be possible without the generous help of numerous volunteers. For a list of who did what in Libevent 2.1, please see the ChangeLog! NOTE: I am very sure that I missed some thing on this list. Caveat haxxor. 0.2. Where to get help Try looking at the other documentation too. All of the header files have documentation in the doxygen format; this gets turned into nice HTML and linked to from the libevent.org website. There is a work-in-progress book with reference manual at http://www.wangafu.net/~nickm/libevent-book/ . You can ask questions on the #libevent IRC channel at irc.oftc.net or on the mailing list at libevent-users@freehaven.net. The mailing list is subscribers-only, so you will need to subscribe before you post. 0.3. Compatibility Our source-compatibility policy is that correct code (that is to say, code that uses public interfaces of Libevent and relies only on their documented behavior) should have forward source compatibility: any such code that worked with a previous version of Libevent should work with this version too. We don't try to do binary compatibility except within stable release series, so binaries linked against any version of Libevent 2.0 will probably need to be recompiled against Libevent 2.1.4-alpha if you want to use it. It is probable that we'll break binary compatibility again before Libevent 2.1 is stable. 1. New APIs and features 1.1. New ways to build libevent We now provide an --enable-gcc-hardening configure option to turn on GCC features designed for increased code security. There is also an --enable-silent-rules configure option to make compilation run more quietly with automake 1.11 or later. You no longer need to use the --enable-gcc-warnings option to turn on all of the GCC warnings that Libevent uses. The only change from using that option now is to turn warnings into errors. For IDE users, files that are not supposed to be built are now surrounded with appropriate #ifdef lines to keep your IDE from getting upset. There is now an alternative cmake-based build process; cmake users should see the relevant sections in the README. 1.2. New functions for events and the event loop If you're running Libevent with multiple event priorities, you might want to make sure that Libevent checks for new events frequently, so that time-consuming or numerous low-priority events don't keep it from checking for new high-priority events. You can now use the event_config_set_max_dispatch_interval() interface to ensure that the loop checks for new events either every N microseconds, every M callbacks, or both. When configuring an event base, you can now choose whether you want timers to be more efficient, or more precise. (This only has effect on Linux for now.) Timers are efficient by default: to select more precise timers, use the EVENT_BASE_FLAG_PRECISE_TIMER flag when constructing the event_config, or set the EVENT_PRECISE_TIMER environment variable to a non-empty string. There is an EVLOOP_NO_EXIT_ON_EMPTY flag that tells event_base_loop() to keep looping even when there are no pending events. (Ordinarily, event_base_loop() will exit as soon as no events are pending.) Past versions of Libevent have been annoying to use with some memory-leak-checking tools, because Libevent allocated some global singletons but provided no means to free them. There is now a function, libevent_global_shutdown(), that you can use to free all globally held resources before exiting, so that your leak-check tools don't complain. (Note: this function doesn't free non-global things like events, bufferevents, and so on; and it doesn't free anything that wouldn't otherwise get cleaned up by the operating system when your process exit()s. If you aren't using a leak-checking tool, there is not much reason to call libevent_global_shutdown().) There is a new event_base_get_npriorities() function to return the number of priorities set in the event base. Libevent 2.0 added an event_new() function to construct a new struct event on the heap. Unfortunately, with event_new(), there was no equivalent for: struct event ev; event_assign(&ev, base, fd, EV_READ, callback, &ev); In other words, there was no easy way for event_new() to set up an event so that the event itself would be its callback argument. Libevent 2.1 lets you do this by passing "event_self_cbarg()" as the callback argument: struct event *evp; evp = event_new(base, fd, EV_READ, callback, event_self_cbarg()); There's also a new event_base_get_running_event() function you can call from within a Libevent callback to get a pointer to the current event. This should never be strictly necessary, but it's sometimes convenient. The event_base_once() function used to leak some memory if the event that it added was never actually triggered. Now, its memory is tracked in the event_base and freed when the event_base is freed. Note however that Libevent doesn't know how to free any information passed as the callback argument to event_base_once is still something you'll might need a way to de-allocate yourself. There is an event_get_priority() function to return an event's priority. By analogy to event_base_loopbreak(), there is now an event_base_loopcontinue() that tells Libevent to stop processing active event callbacks, and re-scan for new events right away. There's a function, event_base_foreach_event(), that can iterate over every event currently pending or active on an event base, and invoke a user-supplied callback on each. The callback must not alter the events or add or remove anything to the event base. We now have an event_remove_timer() function to remove the timeout on an event while leaving its socket and/or signal triggers unchanged. (If we were designing the API from scratch, this would be the behavior of "event_add(ev, NULL)" on an already-added event with a timeout. But that's a no-op in past versions of Libevent, and we don't want to break compatibility.) You can use the new event_base_get_num_events() function to find the number of events active or pending on an event_base. To find the largest number of events that there have been since the last call, use event_base_get_max_events(). You can now activate all the events waiting for a given fd or signal using the event_base_active_by_fd() and event_base_active_by_signal() APIs. On backends that support it (currently epoll), there is now an EV_CLOSED flag that programs can use to detect when a socket has closed without having to read all the bytes until receiving an EOF. 1.3. Event finalization 1.3.1. Why event finalization? Libevent 2.1 now supports an API for safely "finalizing" events that might be running in multiple threads, and provides a way to slightly change the semantics of event_del() to prevent deadlocks in multithreaded programs. To motivate this feature, consider the following code, in the context of a mulithreaded Libevent application: struct connection *conn = event_get_callback_arg(ev); event_del(ev); connection_free(conn); Suppose that the event's callback might be running in another thread, and using the value of "conn" concurrently. We wouldn't want to execute the connection_free() call until "conn" is no longer in use. How can we make this code safe? Libevent 2.0 answered that question by