【原创】libevent功能简介

      下面的说明取自 libevent-1.4.13 中 event.h 头文件。libevent 太有名，讲解的文章网上成堆，自己写点东西留个念想，毕竟好记性不如烂笔头。

  @section intro 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 是一个用于开发可伸缩网络服务器的事件通知程序库。libevent 的 API 提供了一种函数回调机制 -- 当文件描述符上有指定事件发生时或者在指定超时时间到达时 -- 相应的处理函数能够正确回调。更进一步，libevent 同样可以将 signal 或者常规超时事件按上述回调方式进行处理。

  libevent is meant to replace the event loop found in event driven network
  servers. An application just needs to call event_dispatch() and then add or
  remove events dynamically without having to change the event loop.

      libevent 本意用于替代事件驱动网络服务器中的 event loop 处理。应用程序仅需要调用 event_dispatch() ，之后便可以动态地添加或移除 event 且无需对 event loop 做任何改变。

  Currently, libevent supports /dev/poll, kqueue(2), select(2), poll(2) and
  epoll(4). It also has experimental support for real-time signals. 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
  multi-threaded aplications; see Steven Grimm's explanation. Libevent should
  compile on Linux, *BSD, Mac OS X, Solaris and Windows.

      当前，libevent 支持 /dev/poll、kqueue(2)、select(2)、poll(2) 和 epoll(4) 。同时它还对 real-time signal 进行了实验阶段的支持。其内部事件机制完全独立于暴露给调用者的 event API ，所以用户通过简单升级 libevent 库就可以获得相应新特性而无需对之前的应用程序做任何修改。可以说，libevent 仔细考量了可移植行应用程序开发问题，并针对不同操作系统提供其上最佳的可伸缩性事件通知机制。libevent 同样可以用于多线程应用程序。可以参考 Steven Grimm 的解释。libevent 可以在 Linux、*BSD、Mac OS X、Solaris 和 Windows 平台下进行编译。

  @section usage Standard usage
  标准用法

  Every program that uses libevent must include the <event.h> header, and pass
  the -levent flag to the linker.  Before using any of the functions in the
  library, you must call event_init() or event_base_new() to perform one-time
  initialization of the libevent library.

      每一个基于 libevent 开发的程序都必须包含 <event.h> 头文件，并在链接时指定 -levent 标志。在使用库中任何函数之间必须通过调用 event_init() 或 event_base_new() 来对 libevent 库进行一次性初始化。

  @section event Event notification
  事件通知

  For each file descriptor that you wish to monitor, you must declare an event
  structure and call event_set() 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 be allocated on the heap. Finally, you
  call event_dispatch() to loop and dispatch events.

      对于希望监控的每一个文件描述符，你都必须声明一个 event 结构并调用 event_set() 对其成员变量进行初始化。为了使能事件通知功能，你需要通过调用 event_add() 以添加 event 结构到监控事件列表中。event 结构必须在事件通知机制的生命周期中保持有效，所以，event 结构应该在 heap 上被分配。最后，你需要通过调用 event_dispatch() 来开始 loop 以及分发事件。

  @section bufferevent I/O Buffers
  I/O Buffer

  libevent provides an abstraction on top of the regular event callbacks. This
  abstraction is called a buffered event. A buffered event 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.

      libevent 提供了常规事件回调之上的一层抽象。这层抽象被称作 buffered event 。buffered event 提供了可被自动填满和耗尽的输入输出 buffer 。buffered event 的使用者不再直接进行 I/O 操作，而是读时操作输入 buffer ，写时操作输出 buffer 。

  Once initialized via bufferevent_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().

      一旦通过 bufferevent_new() 进行了初始化，结构 bufferevent 就可以在 bufferevent_enable() 和 bufferevent_disable() 中被重复使用。你将通过调用 bufferevent_read() 和 bufferevent_write() 来取代对 socket 直接进行读写操作。

  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.

      当可读时，bufferevent 将尝试从文件描述符上进行读操作，并调用读回调。写回调是在输出 buffer 中的“水位”低于写的“低水位”时被调用执行，该水位值默认为 0 。

  @section timers Timers
  定时器

  libevent can also be used to create timers that invoke a callback after a
  certain amount of time has expired. The evtimer_set() function prepares an
  event struct to be used as a timer. To activate the timer, call
  evtimer_add(). Timers can be deactivated by calling evtimer_del().

      libevent 同样能够被用于创建定时器 -- 在指定时间过去后触发回调函数执行。evtimer_set() 函数将 event 结构中的内容按定时器功能进行设置。激活定时器使用 evtimer_add() ，取消定时器使用 evtimer_del() 。
    
  @section timeouts Timeouts
  超时

  In addition to simple timers, libevent can assign timeout events to file
  descriptors that are triggered whenever a certain amount of time has passed
  with no activity on a file descriptor.  The timeout_set() function
  initializes an event struct for use as a timeout. Once initialized, the
  event must be activated by using timeout_add().  To cancel the timeout, call
  timeout_del().

      除了提供简单定时器功能，libevent 还能够对文件描述符指定超时事件 -- 当该文件描述符在指定超时时间内没有任何活动迹象时，触发超时回调。函数 timeout_set() 用于将 event 结构初始化成超时事件。一旦初始化完成，该事件必须通过调用 timeout_add() 进行激活。可以通过 timeout_del() 对超时事件进行取消。


  @section evdns Asynchronous DNS resolution
  异步 DNS 解析

  libevent provides an asynchronous DNS resolver that should be used instead
  of the standard DNS resolver functions.  These functions can be imported by
  including the <evdns.h> header in your program. Before using any of the
  resolver functions, you must call evdns_init() to initialize the library. To
  convert a hostname to an IP address, you call the evdns_resolve_ipv4()
  function.  To perform a reverse lookup, you would call the
  evdns_resolve_reverse() function.  All of these functions use callbacks to
  avoid blocking while the lookup is performed.

      libevent 提供了一个异步 DNS 解析器以取代标准 DNS 解析器函数。其相应函数可以通过包含 <evdns.h> 头文件来引入。在使用其中的任何解析函数之前，首先要通过调用 evdns_init() 来进行库的初始化。为了将主机名转换成相应的 IP 地址，你可以调用 evdns_resolve_ipv4() 函数。如果你想进行反向查询，则需要调用 evdns_resolve_reverse() 函数。所有这些函数都是通过使用异步回调的方式，来避免查询动作中的阻塞问题。

  @section evhttp Event-driven HTTP servers
  事件驱动 HTTP 服务器

  libevent provides a very simple event-driven HTTP server that can be
  embedded in your program and used to service HTTP requests.

      libevent 提供了一个非常简单的事件驱动 HTTP 服务器，可以嵌入到你自己的应用程序中并用于为 HTTP 请求提供服务。

  To use this capability, you need to include the <evhttp.h> header in your
  program.  You create the server by calling evhttp_new(). Add addresses and
  ports to listen on with evhttp_bind_socket(). You then register one or more
  callbacks to handle incoming requests.  Each URI can be assigned a callback
  via the evhttp_set_cb() function.  A generic callback function can also be
  registered via evhttp_set_gencb(); this callback will be invoked if no other
  callbacks have been registered for a given URI.

      为了获得 HTTP 处理能力，需要包含头文件 <evhttp.h> 在你的应用程序中。你需要通过调用 evhttp_new() 来创建服务器，通过 evhttp_bind_socket() 来添加监听地址和端口号。然后你可以注册一个或者多个回调函数来处理收到的请求。可以通过函数 evhttp_set_cb() 为每一个 URI 指定一个回调函数。你同样可以使用函数 evhttp_set_gencb() 注册一个通用回调处理函数，在没有为指定 URI 注册回调函数的情况下，该回调函数会被调用。

  @section evrpc A framework for RPC servers and clients
  PRC 服务器客户端框架
 
  libevents provides a framework for creating RPC servers and clients.  It
  takes care of marshaling and unmarshaling all data structures.

      libevent 提供一个用于创建 RPC 服务器和客户端的框架。其提供了对所有数据结构的 marshaling 和 unmarshaling 处理。

  @section api API Reference

  To browse the complete documentation of the libevent API, click on any of
  the following links.  

  event.h
  The primary libevent header

  evdns.h
  Asynchronous DNS resolution

  evhttp.h
  An embedded libevent-based HTTP server

  evrpc.h
  A framework for creating RPC servers and clients


=========== 我是分隔线 ============
好文收集：
http://godorz.info/2011/02/the-annotated-libevent-sources-about-structures/