Updates to reference sections for 2.0.9-rc

Ref1_libsetup.txt

@@ -80,6 +80,14 @@ void set_logfile(FILE *f)
 }
 --------
 
+.NOTE
+It is not safe to invoke Libevent functions from within a user-provided
+event_log_cb callback! For instance, if try to write a log callback that
+uses bufferevents to send warning messages to a network socket, you are
+likely to run into strange and hard-to-diagnose bugs. This restriction may
+be removed for some functions in a future version of Libevent.
+
+
 These functions are declared in <event2/event.h>. They first appeared
 in Libevent 1.0c.
 

Ref2_eventbase.txt

@@ -118,7 +118,7 @@ The recognized option values for event_config_set_flag() are:
 - EVENT_BASE_FLAG_NOLOCK: Do not allocate locks for the event_base. Setting
  this option may save a little time for locking and releasing the
  event_base, but will make it unsafe to access it from multiple threads.
-- EVENT_BASE_FLAG_IGNORE_ENV: Do not check the EVENT_NO* environment
+- EVENT_BASE_FLAG_IGNORE_ENV: Do not check the EVENT_* environment
  variables when picking which backend method to use. Think hard before
  using this flag: it can make it harder for users to debug the interactions
  between your program and Libevent.
@@ -129,6 +129,15 @@ The recognized option values for event_config_set_flag() are:
  time the event loop is ready to run timeout callbacks, check it after
  every timeout callback. This can use more CPU than you necessarily
  intended, so watch out!
+- EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST: Tells Libevent that, if it decides to
+ use the epoll backend, it is safe to use the faster "changelist"-based
+ backend. The epoll-changelist backend can avoid needless system calls in
+ cases where the same fd has its status modified more than once between
+ calls to the backend's dispatch function, but it also trigger a kernel bug
+ that causes erroneous results if you give Libevent any fds cloned by
+ dup() or its variants. This flag has no effect if you use a backend
+ other than epoll. You can also turn on the epoll-changelist option by
+ setting the EVENT_EPOLL_uSE_CHANGELIST environment variable.
 
 The above functions that manipulate an event_config all return 0 on success,
 -1 on failure.

Ref3_eventloop.txt

@@ -29,10 +29,11 @@ ready to expire). Once this happens, it marks all triggered events as
 "active", and starts to run them.
 
 You can change the behavior of event_base_loop() by setting one or more flags
-in its 'flags' argument. If EVLOOP_ONCE is set, then the loop will stop
-immediately after running any active events. If EVLOOP_NONBLOCK is set, then
+in its 'flags' argument. If EVLOOP_ONCE is set, then the loop will wait
+until some events become active, then run active events until there are no
+more to run, then return. If EVLOOP_NONBLOCK is set, then
 the loop will not wait for events to trigger: it will only check whether
-any events are ready to trigger immediately.
+any events are ready to trigger immediately, and run their callbacks if so.
 
 When it is done, event_base_loop() returns 0 if it exited normally, and -1 if
 it exited because of some unhandled error in the backend.

Ref5_evutil.txt

@@ -72,6 +72,10 @@ possible value of ev_ssize_t is EV_SSIZE_MAX; the smallest is EV_SSIZE_MIN.
 (The largest possible value for size_t is EV_SIZE_MAX, in case your platform
 doesn't define a SIZE_MAX for you.)
 
+The ev_off_t type is used to represent offset into a file or a chunk of
+memory. It is defined to off_t on platforms with a reasonable off_t
+definition, and to ev_int64_t on Windows.
+
 Some implementations of the sockets API provide a length type, socklen_t, and
 some do not. The ev_socklen_t is defined to this type where it exists, and a
 reasonable default otherwise.
@@ -82,7 +86,8 @@ large enough to hold a pointer without loss of bits.
 
 The ev_ssize_t type was added in Libevent 2.0.2-alpha. The ev_socklen_t type
 was new in Libevent 2.0.3-alpha. The ev_intptr_t and ev_uintptr_t types, and
-the EV_SSIZE_MAX/MIN macros, were added in Libevent 2.0.4-alpha.
+the EV_SSIZE_MAX/MIN macros, were added in Libevent 2.0.4-alpha. The
+ev_off_t type first appeared in Libevent 2.0.9-rc.
 
 Timer portability functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ref6_bufferevent.txt

@@ -773,6 +773,15 @@ event. Only socket-based bufferevents support setfd(). Both return
 The bufferevent_setfd() function was introduced in Libevent 1.4.4;
 the bufferevent_getfd() function was introduced in Libevent 2.0.2-alpha.
 
+.Interface
+[code,C]
+--------
+struct event_base *bufferevent_get_base(struct bufferevent *bev);
+--------
+
+This function returns the event_base of a bufferevent. It was introduced in
+2.0.9-rc.
+
 .Interface
 [code,C]
 --------
@@ -856,6 +865,10 @@ struct bufferevent *bufferevent_new(evutil_socket_t fd,
 int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev);
 --------
 
+The bufferevent_new() function creates a socket bufferevent only, and does so
+on the deprecated "default" event_base. Calling bufferevent_base_set adjusts
+the event_base of a socket bufferevent only.
+
 Instead of setting timeouts as struct timeval, they were set as
 numbers of seconds:
 

Ref6a_advanced_bufferevents.txt

@@ -183,10 +183,11 @@ Setting a rate limit on a bufferevent
 .Interface
 [code,C]
 --------
+#define EV_RATE_LIMIT_MAX EV_SSIZE_MAX
 struct ev_token_bucket_cfg;
 struct ev_token_bucket_cfg *ev_token_bucket_cfg_new(
- ev_uint32_t read_rate, ev_uint32_t read_burst,
- ev_uint32_t write_rate, ev_uint32_t write_burst,
+ size_t read_rate, sizee_t read_burst,
+ size_t write_rate, size_t write_burst,
  const struct timeval *tick_len);
 void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg);
 int bufferevent_set_rate_limit(struct bufferevent *bev,
@@ -204,7 +205,7 @@ defaults to one second. The function may return NULL on error.
 Note that the 'read_rate' and 'write_rate' arguments are scaled in units of
 bytes per tick. That is, if the tick is one tenth of a second, and
 'read_rate' is 300, then the maximum average read rate is 3000 bytes per
-second.
+second. Rate and burst values over EV_RATE_LIMIT_MAX are not supported.
 
 To limit a bufferevent's transfer rate, call bufferevent_set_rate_limit() on
 it with an ev_token_bucket_cfg. The function returns 0 on success, and -1 on

Ref7_evbuffer.txt

@@ -1041,7 +1041,7 @@ mechanisms, where available, with:
 .Interface
 [code,C]
 --------
-int evbuffer_add_file(struct evbuffer *output, int fd, off_t offset,
+int evbuffer_add_file(struct evbuffer *output, int fd, ev_off_t offset,
  size_t length);
 --------
 

Ref8_listener.txt

@@ -34,7 +34,8 @@ When a new connection arrives, it invokes the callback function you give it.
 
 In both functions, the 'base' parameter is an event_base that the listener
 should use to listen for connections. The 'cb' function is a callback to
-invoke when a new connection is received. The 'ptr' pointer will be passed
+invoke when a new connection is received; if 'cb' is NULL, the listener is
+treated as disabled until a callback is set. The 'ptr' pointer will be passed
 to the callback. The 'flags' argument controls the behavior of the listener
 -- more on this below. The 'backlog' parameter controls the maximum number
 of pending connections that the network stack should allow to wait in a
@@ -116,6 +117,19 @@ int evconnlistener_enable(struct evconnlistener *lev);
 
 These functions temporarily disable or reenable listening for new connections.
 
+Adjusting an evconnlistener's callback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.Interface
+[code,C]
+--------
+void evconnlistener_set_cb(struct evconnlistener *lev,
+ evconnlistener_cb cb, void *arg);
+--------
+
+This function adjusts the callback and callback argument of an existing
+evconnlistener. It was introduced in 2.0.9-rc.
+
 Inspecting an evconnlistener
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

Ref9_dns.txt

@@ -194,7 +194,7 @@ EVUTIL_EAI_SYSTEM::
 
 EVUTIL_EAI_CANCEL::
 
- The application requested that this DNS lookup should be cancelled
+ The application requested that this DNS lookup should be canceled
  before it was finished. The evutil_getaddrinfo() function never
  produces this error, but it can come from evdns_getaddrinfo()
  as described in the section below.
@@ -351,7 +351,7 @@ options configured.
 When you no longer need an evdns_base, you can free it with
 evdns_base_free. If its 'fail_request' argument is true, it will
 make all in-flight requests get their callbacks invoked with a
-'cancelled' error code before it frees the base.
+'canceled' error code before it frees the base.
 
 Initializing evdns from the system configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^