Start editing the changelog for 2.1.3-alpha

2 files changed, 273 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index 50c65270..a04d955c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,151 @@
-Changes in version 2.1.3-alpha (?? ??? 201?)
+Changes in version 2.1.3-alpha (?? ??? 2013)
+
+ Libevent 2.1.3-alpha fixes various bugs, adds new unit tests, and cleans
+ up the code in a couple of places. It has a new callback in evhttp for
+ reporting errors during a request, a new feature for allowing evdns to
+ not keep the event_base looping when there are no requests inflight, and
+ example code for writing an https client.
+
+ Libevent 2.1.3-alpha also has an important new (experimental) event
+ finalization feature to allow safe event teardown in multithreaded
+ programs. This ought to fix the longstanding bug with deadlocks in
+ multithreaded use of SSL-based bufferevents that some people have been
+ experiencing since Libevent 2.0.
+
+
+ Core (event finalization)
+   o Implement event_finalize() and related functions to avoid certain
+     deadlocks (8eedeab)
+   o Use finalization feature so bufferevents can avoid deadlocks (02fbf68)
+   o Always run pending finalizers when event_base_free() is called (e9ebef8)
+   o Remove bufferevent_del_generic_timeout_cbs as now unused (4ea4c6a)
+   o More documentation for finalization feature (a800b91)
+   o Make the event_finalize* functions return an error code (5d11f4f)
+   o Mark the finalize stuff as experiemental in case it needs to
+     change (23e2e29)
+
+ Evdns
+   o evdns: New flag to make evdns not prevent the event loop from
+     exiting (6b7fa62 Azat Khuzhin)
+
+ Bugfixes (Core)
+   o Make event_remove_timer behave correctly with persistent timers (5623e80)
+   o Unit test for event_remove_timer with EV_PERSIST. (96150dd)
+   o Double-check next timeout when adding events (9443868 Nate Rosenblum)
+   o event_base_update_cache_time should be a no-op if the loop isn't
+     running (5e6fa2a)
+
+ Bugfixes (evhttp, crash fix, from 2.0)
+   o fix #73 and fix http_connection_fail_test to catch it (b618204 Greg Hazel)
+
+ Bugfixes (compilation and portability, from 2.0)
+   o Fix compilation with WIN32_HAVE_CONDITION_VARIABLES enabled (7e45739)
+   o Fix missing AC_PROG_SED on older Autoconfs (9ab2b3f Tay Ray Chuan)
+   o Backport libevent to vanilla Autoconf 2.59 (as used in RHEL5)
+     (74d4c44 Kevin Bowling)
+   o Use AC_CONFIG_HEADERS in place of AM_CONFIG_HEADERS for autmake
+     1.13 compat (817ea36)
+   o Rename configure.in to configure.ac to appease newer autoconfs (0c79787)
+   o Avoid using top_srcdir in TESTS: new automakes do not like this (a55514e)
+
+ Bugfixes (resource leaks/lock errors on error, from 2.0)
+   o Avoid leaking fds on evconnlistener with no callback set (69db261)
+   o Avoid double-close on getsockname error in evutil_ersatz_socketpair
+     (0a822a6)
+   o Fix a locking error in bufferevent_socket_get_dns_error. (0a5eb2e)
+
+ Documentation Fixes (from 2.0)
+   o Fix a mistake in evbuffer_remove() arguments in example http server code
+     (c322c20 Gyepi Sam)
+   o Fix a typo in a comment in buffer.h. Spotted by Alt_F4 (773b0a5)
+
+ Documentation Fixes
+   o minor documentation typos (809586a Patrick Pelletier)
+   o Fix cut-and-paste err in whatsnew-2.1 (49905ac)
+   o Fix comment to refer to sample/include.am correctly (9e8cdf3 Sebastian
+     Hahn)
+   o Fix typo : Dispatching instead of Dispaching (0c2bacc Volker Lendecke)
+   o fix some hinky indentation in evhttp_make_request (80e220e Patrick
+     Pelletier)
+   o "buffer" spelling (a452811 Patrick Pelletier)
+   o Specify return behavior in header for evbuffer_pullup() in corner case
+     (cf8d1cd Dan Petro)
+   o Clarify an important point about event_base_foreach_event() (920a5e6)
+
+ Compilation Fixes/Tool Support
+   o avoid valgrind false positive by zeroing epoll_event (1258614 Patrick
+     Pelletier)
+   o Fix harmless clang enum warning (b452a43 Sebastian Hahn)
+   o remove all exes on "make clean", not just regress.exe (974bfa0 Patrick
+     Pelletier)
+   o Make --disable-libevent-regress work again (787fd74)
+   o Do not build strlcpy.c when it will have no code. (4914620)
+
+ Portability Fixes
+   o When EWOULDBLOCK is not EAGAIN, treat it as equivalent to it (bf7a0ff)
+   o Preliminary changes for Minix3. (0dda56a Nicholas Heath)
+   o Use AC_CONFIG_HEADERS in place of AM_CONFIG_HEADERS for autmake 1.13
+     compat (bf278b)
+   o Avoid using $(top_srcdir) in TESTS. (2863c83)
+   o build test/test-script.sh on systems with a less-featureful $< (f935e21)
+   o Implement EVUTIL_ERR_IS_EAGAIN on windows. (42aaf4d)
+
+ Evhttp changes:
+   o Fix ipv6 support for http. When URL contain domain, not IP
+     address. (71e709c Azat Khuzhin)
+   o uri decode: fix for warning "use of uninitialised value" (64b6ece Azat
+     Khuzhin)
+   o uri decode: changed the test for the existence of the next character
+     (e1903e3 Azat Khuzhin)
+   o Move prototype of evhttp_decode_uri_internal() to http-internal.h
+     (de8101a Azat Khuzhin)
+   o Test: decoding just part of string with evhttp_decode_uri_internal()
+     (1367653 Azat Khuzhin)
+   o Add new error_cb for actual reporting of HTTP request errors. (7b07719
+     Azat Khuzhin)
+   o Add test for EVREQ_HTTP_REQUEST_CANCEL into http_cancel_test() (862c217
+     Azat Khuzhin)
+   o Drop extra header http_struct.h from regress_http.c (54cc800 Azat Khuzhin)
+
+ Testing
+   o Add regress test ipv6_for_domain. (9ec88bd Azat Khuzhin)
+   o Add an environment variable (EVENT_DEBUG_MODE) to run unit tests in debug
+     mode (2fad0f3)
+   o Add a test with an active_later event at event_base_free time. (1c3147f)
+   o Make all tests pass under EVENT_DEBUG_MODE=1 (b1b054f)
+   o Add some verbose notes to bufferevent unit tests (9d893c9)
+   o New test for active_later->active transition on event_active (a153874)
+   o New tests for event_base_foreach_event() (0b096ef)
+   o Unit tests for event_base_gettimeofday_cached() and
+     event_base_update_cache_time() (30ea291)
+   o A test for event_get_assignment() (f09629e)
+   o More unit tests for initializing common timeouts. (d596739)
+   o Fix a bug in the new main/event_foreach test (702c9aa)
+
+ Windows:
+   o use FormatMessage for winsock errors (0c6ec5d, 2078e9b, 4ccdd53, c9ad3af
+     Patrick Pelletier)
+   o a program to print out the error strings for winsock errors (7296512
+     Patrick Pelletier)
+   o Fix a warning introduced in 0c6ec5d8 (eeb700c)
+   o Fix another warning introduced in 0c6ec5d8 (ed26561)
+
+ Examples (http)
+   o Add sample/https-client.c, an example of stacking evhttp as a client on
+     top of bufferevent_ssl. (be46c99 Catalin Patulea)
+   o use ${OPENSSL_LIBS} instead of -lssl -lcrypto (bf31fa5 Patrick Pelletier)
+   o https-client was putting newlines at 256-byte boundaries (42d7441 Patrick
+     Pelletier)
+   o better handling of OpenSSL errors (5754d96 Patrick Pelletier)
+   o use Debian's default root certificate location (aacd674 Patrick Pelletier)
+   o use iSECPartners code to validate hostname in certificate (64d9f16
+     Patrick Pelletier)
+   o avoid sign mismatch warning in openssl_hostname_validation.c (6021cb5
+     Patrick Pelletier)
+   o pull in wildcard matching code from cURL (4db9da6 Patrick Pelletier)
+   o Another tweak to https-client.c (95acdaa)
+   o Remove http_struct.h usage in sample/https-client.c (8a90a85)
+
 
 
 Changes in version 2.1.2-alpha (18 Nov 2012)
diff --git a/whatsnew-2.1.txt b/whatsnew-2.1.txt
index fc829ac1..c0ee7cf7 100644
--- a/whatsnew-2.1.txt
+++ b/whatsnew-2.1.txt
@@ -41,7 +41,7 @@
 
   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.1-alpha if you
+  probably need to be recompiled against Libevent 2.1.3-alpha if you
   want to use it.  It is probable that we'll break binary compatibility
   again before Libevent 2.1 is stable.
 
@@ -146,7 +146,113 @@
   that's a no-op in past versions of Libevent, and we don't want to
   break compatibility.)
 
-1.3. New debugging features
+1.3. Event finalization
+
+  [NOTE: This is an experimental feature in Libevent 2.1.3-alpha. Though
+  it seems solid so far, its API might change between now and the first
+  release candidate for Libevent 2.1.]
+
+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 saying that the event_del()
+  call should block if the event's callback is running in another
+  thread.  That way, we can be sure that event_del() has canceled the
+  callback (if the callback hadn't started running yet), or has waited
+  for the callback to finish.
+
+  But now suppose that the data structure is protected by a lock, and we
+  have the following code:
+
+        void check_disable(struct connection *connection) {
+            lock(connection);
+            if (should_stop_reading(connection))
+                    event_del(connection->read_event);
+            unlock(connection);
+        }
+
+  What happens when we call check_disable() from a callback and from
+  another thread?  Let's say that the other thread gets the lock
+  first.  If it decides to call event_del(), it will wait for the
+  callback to finish.  But meanwhile, the callback will be waiting for
+  the lock on the connection.  Since each threads is waiting for the
+  other one to release a resource, the program will deadlock.
+
+  This bug showed up in multithreaded bufferevent programs in 2.1,
+  particularly when freeing bufferevents.  (For more information, see
+  the "Deadlock when calling bufferevent_free from an other thread"
+  thread on libevent-users starting on 6 August 2012 and running through
+  February of 2013.  You might also like to read my earlier writeup at
+  http://archives.seul.org/libevent/users/Feb-2012/msg00053.html and
+  the ensuing discussion.)
+
+1.3.2. The EV_FINALIZE flag and avoiding deadlock
+
+  To prevent the deadlock condition described above, Libevent
+  2.1.3-alpha adds a new flag, "EV_FINALIZE".  You can pass it to
+  event_new() and event_assign() along with EV_READ, EV_WRITE, and the
+  other event flags.
+
+  When an event is constructed with the EV_FINALIZE flag, event_del()
+  will not block on that event, even when the event's callback is
+  running in another thread.  By using EV_FINALIZE, you are therefore
+  promising not to use the "event_del(ev); free(event_get_callback_arg(ev));"
+  pattern, but rather to use one of the finalization functions below to
+  clean up the event.
+
+  EV_FINALIZE has no effect on a single-threaded program, or on a
+  program where events are only used from one thread.
+
+
+  There are also two new variants of event_del() that you can use for
+  more fine-grained control:
+     event_del_noblock(ev)
+     event_del_block(ev)
+  The event_del_noblock() function will never block, even if the event
+  callback is running in another thread and doesn't have the EV_FINALIZE
+  flag.  The event_del_block() function will _always_ block if the event
+  callback is running in another thread, even if the event _does_ have
+  the EV_FINALIZE flag.
+
+  [A future version of Libevent may have a way to make the EV_FINALIZE
+  flag the default.]
+
+1.3.3. Safely finalizing events
+
+  To safely tear down an event that may be running, Libevent 2.1.3-alpha
+  introduces event_finalize() and event_free_finalize(). You call them
+  on an event, and provide a finalizer callback to be run on the event
+  and its callback argument once the event is definitely no longer
+  running.
+
+  With event_free_finalize(), the event is also freed once the finalizer
+  callback has been invoked.
+
+  A finalized event cannot be re-added or activated.  The finalizer
+  callback must not add events, activate events, or attempt to
+  "resucitate" the event being finalized in any way.
+
+  If any finalizer callbacks are pending as the event_base is being
+  freed, they will be invoked.  You can override this behavior with the
+  new function event_base_free_nofinalize().
+
+1.4. New debugging features
 
   You can now turn on debug logs at runtime using a new function,
   event_enable_debug_logging().
@@ -158,7 +264,7 @@
   There's also been some work done to try to make the debugging logs
   more generally useful.
 
-1.4. New evbuffer functions
+1.5. New evbuffer functions
 
   In Libevent 2.0, we introduced evbuffer_add_file() to add an entire
   file's contents to an evbuffer, and then send them using sendfile() or
@@ -198,7 +304,7 @@
   evbuffer_readln() now supports an EVBUFFER_EOL_NUL argument to fetch
   NUL-terminated strings from buffers.
 
-1.5. New functions and features: bufferevents
+1.6. New functions and features: bufferevents
 
   You can now use the bufferevent_getcb() function to find out a
   bufferevent's callbacks.  Previously, there was no supported way to do
@@ -219,7 +325,7 @@
   You can find the priority at which a bufferevent runs with
   bufferevent_get_priority().
 
-1.6. New functions and features: evdns
+1.7. New functions and features: evdns
 
   The previous evdns interface used an "open a test UDP socket" trick in
   order to detect IPv6 support.  This was a hack, since it would
@@ -227,7 +333,14 @@
   packets were sent.  The current evdns interface-detection code uses
   the appropriate OS functions to see which interfaces are configured.
 
-1.7. New functions and features: evconnlistener
+  The evdns_base_new() function now has multiple possible values for its
+  second (flags) argument.  Using 1 and 0 have their old meanings, though the
+  1 flag now has a symbolic name of EVDNS_BASE_INITIALIZE_NAMESERVERS.
+  A second flag is now supported too: the EVDNS_BASE_DISABLE_WHEN_INACTIVE
+  flag, which tells the evdns_base that it should not prevent Libevent from
+  exiting while it has no DNS requests in progress.
+
+1.8. New functions and features: evconnlistener
 
   Libevent 2.1 adds the following evconnlistener flags:
 
@@ -245,7 +358,7 @@
   the accepted sockets themselves.  That's almost never what you want.
   Now, it applies both to the listener and the accepted sockets.
 
-1.8. New functions and features: evhttp
+1.9. New functions and features: evhttp
 
   **********************************************************************
   NOTE: The evhttp module will eventually be deprecated in favor of Mark
@@ -274,6 +387,11 @@
   The socket errno value is now preserved when invoking an http error
   callback.
 
+  There's a new kind of request callback for errors; you can set it with
+  evhttp_request_set_error_cb(). It gets called when there's a request error,
+  and actually reports the error code and lets you figure out which request
+  failed.
+
 2. Cross-platform performance improvements
 
 2.1. Better data structures