|
libevent
2.2.1
Event notification library
|
Libevent is an event notification library for developing scalable network servers. The Libevent API provides a mechanism to execute a callback function when a specific event occurs on a file descriptor or after a timeout has been reached. Furthermore, Libevent also support callbacks due to signals or regular timeouts.
Libevent is meant to replace the event loop found in event driven network servers. An application just needs to call event_base_dispatch() and then add or remove events dynamically without having to change the event loop.
Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2), epoll(4), and evports. The internal event mechanism is completely independent of the exposed event API, and a simple update of Libevent can provide new functionality without having to redesign the applications. As a result, Libevent allows for portable application development and provides the most scalable event notification mechanism available on an operating system. Libevent can also be used for multithreaded programs. Libevent should compile on Linux, *BSD, Mac OS X, Solaris and, Windows.
Every program that uses Libevent must include the <event2/event.h> header, and pass the -levent flag to the linker. (You can instead link -levent_core if you only want the main event and buffered IO-based code, and don't want to link any protocol code.)
Before you call any other Libevent functions, you need to set up the library. If you're going to use Libevent from multiple threads in a multithreaded application, you need to initialize thread support – typically by using evthread_use_pthreads() or evthread_use_windows_threads(). See <event2/thread.h> for more information.
This is also the point where you can replace Libevent's memory management functions with event_set_mem_functions, and enable debug mode with event_enable_debug_mode().
Next, you need to create an event_base structure, using event_base_new() or event_base_new_with_config(). The event_base is responsible for keeping track of which events are "pending" (that is to say, being watched to see if they become active) and which events are "active". Every event is associated with a single event_base.
For each file descriptor that you wish to monitor, you must create an event structure with event_new(). (You may also declare an event structure and call event_assign() to initialize the members of the structure.) To enable notification, you add the structure to the list of monitored events by calling event_add(). The event structure must remain allocated as long as it is active, so it should generally be allocated on the heap.
Finally, you call event_base_dispatch() to loop and dispatch events. You can also use event_base_loop() for more fine-grained control.
Currently, only one thread can be dispatching a given event_base at a time. If you want to run events in multiple threads at once, you can either have a single event_base whose events add work to a work queue, or you can create multiple event_base objects.
Libevent provides a buffered I/O abstraction on top of the regular event callbacks. This abstraction is called a bufferevent. A bufferevent provides input and output buffers that get filled and drained automatically. The user of a buffered event no longer deals directly with the I/O, but instead is reading from input and writing to output buffers.
Once initialized via bufferevent_socket_new(), the bufferevent structure can be used repeatedly with bufferevent_enable() and bufferevent_disable(). Instead of reading and writing directly to a socket, you would call bufferevent_read() and bufferevent_write().
When read enabled the bufferevent will try to read from the file descriptor and call the read callback. The write callback is executed whenever the output buffer is drained below the write low watermark, which is 0 by default.
See <event2/bufferevent*.h> for more information.
Libevent can also be used to create timers that invoke a callback after a certain amount of time has expired. The evtimer_new() macro returns an event struct to use as a timer. To activate the timer, call evtimer_add(). Timers can be deactivated by calling evtimer_del(). (These macros are thin wrappers around event_new(), event_add(), and event_del(); you can also use those instead.)
Libevent provides an asynchronous DNS resolver that should be used instead of the standard DNS resolver functions. See the <event2/dns.h> functions for more detail.
Libevent provides a very simple event-driven HTTP server that can be embedded in your program and used to service HTTP requests.
To use this capability, you need to include the <event2/http.h> header in your program. See that header for more information.
Libevent provides a framework for creating RPC servers and clients. It takes care of marshaling and unmarshaling all data structures.
To browse the complete documentation of the libevent API, click on any of the following links.
event2/event.h The primary libevent header
event2/thread.h Functions for use by multithreaded programs
event2/buffer.h and event2/bufferevent.h Buffer management for network reading and writing
event2/util.h Utility functions for portable nonblocking network code
event2/dns.h Asynchronous DNS resolution
event2/http.h An embedded libevent-based HTTP server
event2/rpc.h A framework for creating RPC servers and clients
event2/watch.h "Prepare" and "check" watchers.
1.8.17