Skip to content
Browse files

Revise sections up to Ref5 for 2.0.3-alpha.

  • Loading branch information...
1 parent a77e493 commit fa74aaa3c55f9d6d3c32abb907870501d1c66b66 Nick Mathewson committed Nov 20, 2009
Showing with 94 additions and 19 deletions.
  1. +0 −7 00_about.txt
  2. +12 −5 Ref0_meta.txt
  3. +36 −2 Ref1_libsetup.txt
  4. +16 −3 Ref2_eventbase.txt
  5. +17 −0 Ref3_eventloop.txt
  6. +13 −2 Ref4_event.txt
7 00_about.txt
@@ -19,10 +19,3 @@ A note on examples
The examples in this document should work all right on Linux, FreeBSD,
OpenBSD, NetBSD, Mac OS X, Solaris, and Android. Some of the examples
may not compile on Windows.
-Why Libevent 2.0?
-XXX Foo.
17 Ref0_meta.txt
@@ -50,12 +50,12 @@ bufferevent::
sockets are ready to do, they let you know when IO has actually
-// FIXME say this only when it's true. On Windows, this interface
-// can bypass Libevent's event-based core entirely, and use the
-// much-faster IOCP implementation.
+ The bufferevent interface also has multiple backends, so that
+ it can take advantage of systems that provide faster ways to do
+ nonblocking IO, such as the Windows IOCP API.
- This module implements the the buffers underlying bufferevents,
+ This module implements the buffers underlying bufferevents,
and provides functions for efficient and/or convenient access.
@@ -88,7 +88,7 @@ libevent_extra::
This library exists for historical reasons; it contains the
contents of both libevent_core and libevent_extra. You shouldn't
- use it; it will go away in a future version of Libevent.
+ use it; it may go away in a future version of Libevent.
The following libraries are installed only on some platforms:
@@ -99,6 +99,13 @@ libevent_pthreads::
to use Libevent unless you are _actually_ using Libevent in a
multithreaded way.
+ This library provides support for encrypted communications using
+ bufferevents and the OpenSSL library. It is separated from
+ libevent_core so that you don't need to link against OpenSSL
+ to use Libevent unless you are _actually_ using encrypted
+ connections.
The Headers
38 Ref1_libsetup.txt
@@ -80,6 +80,39 @@ void set_logfile(FILE *f)
These functions are declared in <event2/event.h>. They first appeared
in Libevent 1.0c.
+Handling fatal errors
+When Libevent detects a non-recoverable internal error (such as a corrupted
+data structure or a ), its default behavior is to call exit() to leave the
+currently running process. These errors almost always mean that there is a
+bug somewhere: either in your code, or in Libevent itself.
+You can override Libevent's behavior if you want your application to handle
+fatal errors more gracefully, by providing a function that Libevent should
+call in lieu of exiting.
+typedef void (*event_fatal_cb)(int err);
+void event_set_fatal_callback(event_fatal_cb cb);
+To use these functions, you first define a new function that Libevent should
+call upon encountering a fatal error, then you pass it to
+event_set_fatal_callback(). Later, if Libevent encounters a fatal error, it
+will call the function you provided.
+Your function *should not* return control to Libevent; doing so may cause
+undefined behavior, and Libevent might exit anyway to avoid crashing. Once
+your function has been called, you should not call any other Libevent
+These functions are declared in <event2/event.h>. They first appeared
+in Libevent 2.0.3-alpha.
Memory management
@@ -249,6 +282,7 @@ void evthread_set_id_callback(
unsigned long (*id_fn)(void));
Your locks will be passed around as the void * type. The alloc_fn
argument must be a function that allocates a new lock; the free_fn
argument must be a function that frees a lock allocated with alloc_fn.
@@ -303,8 +337,8 @@ you'll want to detect the Libevent version, so that you can:
-#define LIBEVENT_VERSION_NUMBER 0x02000100
+#define LIBEVENT_VERSION_NUMBER 0x02000300
const char *event_get_version(void);
ev_uint32_t event_get_version_number(void);
19 Ref2_eventbase.txt
@@ -90,7 +90,10 @@ int event_config_require_features(struct event_config *cfg,
enum event_method_feature feature);
enum event_base_config_flag {
int event_config_set_flag(struct event_config *cfg,
enum event_base_config_flag flag);
@@ -99,8 +102,8 @@ int event_config_set_flag(struct event_config *cfg,
Calling event_config_avoid_method tells Libevent to avoid a specific
available backend by name. Calling event_config_require_feature() tells
Libevent not to use any backend that cannot supply all of a set of features.
-// Calling event_config_set_flag() XXXXX FIXME
+Calling event_config_set_flag() tells Libevent to set one or more of
+the run-time flags below when constructing the event base.
The recognized feature values for event_config_require_features are:
@@ -119,6 +122,13 @@ The recognized option values for event_config_set_flag() are:
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.
+- EVENT_BASE_FLAG_STARTUP_IOCP: On Window only, this flag makes Libevent
+ enable any necessary IOCP dispatch logic on startup, rather than
+ on-demand.
+- EVENT_BASE_FLAG_NO_CACHE_TIME: Instead of checking the current time every
+ 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!
The above functions that manipulate an event_config all return 0 on success,
-1 on failure.
@@ -360,3 +370,6 @@ functions, except that they took no base argument.
| event_base_get_method() | event_get_method()
+// FIXME Undocumented:
+// event_base_make_notifiable()
17 Ref3_eventloop.txt
@@ -162,6 +162,23 @@ while (1)
+Sometimes you may want to tell whether your call to event_base_dispatch() or
+event_base_loop() exited normally, or because of a call to
+event_base_loopexit() or event_base_break(). You can use these functions to
+tell whether loopexit or break was called:
+int event_base_got_exit(struct event_base *base);
+int event_base_got_break(struct event_base *base);
+These two functions will return true if the loop was stopped with
+event_base_loopexit() or event_base_break() respectively, and false
+otherwise. Their values will be reset the next time you start the event
These functions are declared in <event2/event.h>. The event_break_loopexit()
function was first implemented in Libevent 1.0c; event_break_loopbreak() was
first implemented in Libevent 1.4.3.
15 Ref4_event.txt
@@ -37,7 +37,7 @@ To create a new event, use the event_new() interface.
#define EV_TIMEOUT 0x01
#define EV_READ 0x02
-v#define EV_WRITE 0x04
+#define EV_WRITE 0x04
#define EV_SIGNAL 0x08
#define EV_PERSIST 0x10
#define EV_ET 0x20
@@ -65,7 +65,7 @@ pending, call event_add() (documented below).
To deallocate an event, call event_free(). It is safe to call
event_free() on an event that is pending or active: doing so makes the
-event non-pending and in-active before deallocating it.
+event non-pending and inactive before deallocating it.
@@ -281,6 +281,17 @@ event base. Doing so can lead to extremely hard-to-diagnose
errors. If the event is already initialized and pending, call
event_del() on it *before* you call event_assign() on it again.
+There are convenience macros you can use to event_assign() a timeout-only or
+a signal event:
+#define evtimer_assign(event, base, callback, arg) \
+ event_assign(event, base, -1, 0, callback, arg)
+#define evsignal_assign(event, base, signum, callback, arg) \
+ event_assign(event, base, signum, EV_SIGNAL|EV_PERSIST, callback, arg)
The event_assign() function is defined in <event2/event.h>. It has
existed since Libevent 2.0.1-alpha. The event structure itself is
defined in <event2/event_struct.h>.

0 comments on commit fa74aaa

Please sign in to comment.
Something went wrong with that request. Please try again.