libevent  2.2.1
Event notification library
libevent Documentation

Introduction

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.

Standard usage

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.)

Library setup

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().

Creating an event base

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.

Event notification

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.

Dispatching events.

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.

I/O Buffers

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.

Timers

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.)

Asynchronous DNS resolution

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.

Event-driven HTTP servers

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.

A framework for RPC servers and clients

Libevent provides a framework for creating RPC servers and clients. It takes care of marshaling and unmarshaling all data structures.

API Reference

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.