Libevent：2设置

Libevent有一些整个进程共享的全局设置。这些设置会影响到整个的库。因此必须在调用Libevent其他函数之前进行设置，否则，LIbevent就会陷入不一致的状态。

一：Libevent中的日志信息

Libevent可以记录内部的error和warning信息，而且如果在编译时设置的话，它还可以记录debug消息。默认情况下，这些信息都会写到stderr中。可以通过提供自己的日志函数来改变该行为。

#define  EVENT_LOG_DEBUG  0

#define  EVENT_LOG_MSG   1

#define  EVENT_LOG_WARN  2

#define  EVENT_LOG_ERR   3

/* Deprecated; see note at theend of this section */

#define _EVENT_LOG_DEBUG  EVENT_LOG_DEBUG

#define _EVENT_LOG_MSG   EVENT_LOG_MSG

#define _EVENT_LOG_WARN  EVENT_LOG_WARN

#define _EVENT_LOG_ERR   EVENT_LOG_ERR

typedef void(*event_log_cb)(int severity, const char *msg);

void event_set_log_callback(event_log_cb cb);

如果想要改变Libevent默认的日志行为，需要编写自己的日志函数，该日志函数要符合event_log_cb原型，并且将该函数作为参数传入到event_set_log_callback()。当Libevent需要记录日志的时候，会将日志信息传入到你提供的函数中。如果想恢复到Libevent的默认日志行为，则只需要以NULL为参数调用event_set_log_callback()即可。

实例：

#include <event2/event.h>

#include <stdio.h>

static void discard_cb(int severity, const char *msg)

{

/* This callback does nothing. */

}

static FILE *logfile = NULL;

static void write_to_file_cb(int severity, const char *msg)

{

const char *s;

if (!logfile)

return;

switch (severity) {

case _EVENT_LOG_DEBUG: s ="debug"; break;

case _EVENT_LOG_MSG:   s = "msg";   break;

case _EVENT_LOG_WARN:  s = "warn";  break;

case _EVENT_LOG_ERR:   s = "error"; break;

default:               s = "?";     break; /* never reached */

}

fprintf(logfile, "[%s] %s\n", s,msg);

}

/* Turn off all logging from Libevent. */

void suppress_logging(void)

{

event_set_log_callback(discard_cb);

}

/* Redirect all Libevent log messages to the C stdio file 'f'. */

void set_logfile(FILE *f)

{

logfile = f;

event_set_log_callback(write_to_file_cb);

}

注意：在用户提供的event_log_cb回调函数中调用Libevent 函数是不安全的。比如，在自己写的日志回调函数中，使用bufferevents将warning信息发送到网络上，那么很可能会遇见奇怪且难以调试的bug。未来Libevent版本中，针对某些函数有可能会去除该限制。

通常，debug级别的日志是禁用的，并且不会发送到日志回调函数中。如果在构建Libevent时支持的话，可以手动启用。

#define EVENT_DBG_NONE  0

#define EVENT_DBG_ALL      0xffffffffu

void  event_enable_debug_logging(ev_uint32_t which);

在多数环境下，debug信息是冗长且无用的。使用EVENT_DBG_NONE参数调用event_enable_debug_logging() 可以得到默认行为；使用EVENT_DBG_ALL调用该函数，可以打开所有支持的debug日志。未来版本中可能会支持更加精细的选项。这些函数在<event2/event.h>声明。

兼容性：在Libevent2.0.19-stable版本之前，EVENT_LOG_*这样的宏名称是以下划线开头的，比如_EVENT_LOG_DEBUG，_EVENT_LOG_MSG, _EVENT_LOG_WARN和_EVENT_LOG_ERR。这些古老的名字已经废弃，而且只能在Libevent 2.0.18-stable之前的版本中使用。未来版本中，他们可能会被移除。

二：处理致命错误

当Libevent遇到一个无法恢复的内部错误的时候，它的默认行为是调用exit()或abort()退出当前运行的进程。这些错误意味着程序存在bug，要么在程序的代码中，要么在Libevent本身。

如果希望应用进程更加优雅的处理致命错误的话，可以改变Libevent的这种默认行为。通过提供另一个函数以供Libevent调用，替代退出这种默认行为。

typedef  void (*event_fatal_cb)(int 
err);

void  event_set_fatal_callback(event_fatal_cb  cb);

首先定义一个新的函数，该函数在Libevent遇到致命错误的时候会被调用，然后将新定义的函数作为参数传给event_set_fatal_callback()函数。之后，当Libevent遇到致命错误时，将会调用你提供的新函数。

注意：替代函数不要将控制返回到Libevent，否则会遇到非定义的行为，而且Libevent会退出。所以一旦你的函数被调用，就不要再次调用任何其他的Libevent函数。

三：内存管理

默认情况下，Libevent使用C库提供的内存管理函数从堆上分配内存。你可以提供自己的内存管理函数以供Libevent使用，从而替代malloc, realloc和free。如果你有更有效的内存分配器，或者有可以检测内存泄露的内存分配器，你就可以这样做。

void  event_set_mem_functions(void *(*malloc_fn)(size_t sz),

void*(*realloc_fn)(void *ptr, size_t sz),

void(*free_fn)(void *ptr));

下面是一个简单替换Libevent分配函数的例子。在实际环境中，需要加上锁机制，以防止在多线程环境中遇到错误。

#include <event2/event.h>

#include <sys/types.h>

#include <stdlib.h>

/* This union's purpose is tobe as big as the largest of all the

* types it contains. */

union alignment {

size_t sz;

void *ptr;

double dbl;

};

/* We need to make sure that  everything we return is on the right

alignment to hold anything, including adouble. */

#define ALIGNMENT sizeof(union  alignment)

/* We need to do this  cast-to-char*  trick on our pointers to adjust

them; doing arithmetic on a void* is notstandard. */

#define OUTPTR(ptr)  (((char*)ptr)+ALIGNMENT)

#define INPTR(ptr)      (((char*)ptr)-ALIGNMENT)

static  size_t  total_allocated = 0;

static  void*  replacement_malloc(size_t  sz)

{

void *chunk = malloc(sz + ALIGNMENT);

if (!chunk) return chunk;

total_allocated += sz;

*(size_t*)chunk = sz;

return OUTPTR(chunk);

}

static void*  replacement_realloc(void *ptr, size_t sz)

{

size_t old_size = 0;

if (ptr) {

ptr = INPTR(ptr);

old_size = *(size_t*)ptr;

}

ptr = realloc(ptr,  sz + ALIGNMENT);

if (!ptr)

return NULL;

*(size_t*)ptr = sz;

total_allocated = total_allocated - old_size + sz;

return OUTPTR(ptr);

}

static void replacement_free(void*ptr)

{

ptr = INPTR(ptr);

total_allocated  -= *(size_t*)ptr;

free(ptr);

}

void start_counting_bytes(void)

{

event_set_mem_functions(replacement_malloc,

replacement_realloc,

replacement_free);

}

注意：

1：替换内存管理函数，将会影响到Libevent中所有内存分配，调整大小和释放内存操作。因此，需要在调用任何其他Libevent函数之前，进行这种替换。否则的话，Libevent将会使用你提供的free函数，来释放由C库的malloc函数申请的空间。

2：你的malloc和realloc函数应该同C库返回的内存块一样，具有同样的内存地址对齐特性。

3：你的realloc函数需要正确的处理realloc(NULL,sz)（也就是将其当做malloc（sz）处理）。

4：你的realloc函数需要正确的处理realloc(ptr,0)（也就是将其当做free(ptr)处理）。

5：你的free函数无需处理free（Null）。

6：你的malloc函数，无需处理malloc（0）。

7：如果在多线程环境中使用Libevent的话，需要保证你的内存管理函数是线程安全的。

8：如果替代了Libevent内存管理函数，那么Libevent将会使用替代函数来分配内存，所以，应该使用free的替代版本来释放由Libevent返回的内存。

event_set_mem_functions()函数在<event2/event.h>声明。

Libevent可以在构建时禁用event_set_mem_functions()函数。如果禁用的话，那么使用event_set_mem_functions的代码将不会编译或链接。在Libevent2.0.2-alpha以及之后的版本中，可以通过检查宏定义EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED，来判断函数event_set_mem_functions是否被禁用。

四：线程和锁

如你所知，同一时刻，多个线程访问同一个数据是不安全的。多线程环境下，Libevent的结构体有三种工作方式：

一些结构体是单线程使用的：多线程同时使用是不安全的；

一些结构体带有可选的锁：针对这种结构体，你可以告诉Libevent，是否会需要多个线程同时访问它

一些结构体是带有强制锁：如果Libevent支持锁机制的话，那么这些结构体永远是线程安全的。

为了获得Libevent中的锁机制，必须在调用任何分配多线程共享的结构体的函数之前，告诉Libevent使用哪些锁函数。

如果使用pthreads库，或者使用原有的Windows多线程代码，那么已经有设置好的libevent预定义函数，能够正确的使用pthreads或者Windows函数。

#ifdef  WIN32

int  evthread_use_windows_threads(void);

#define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED

#endif

#ifdef _EVENT_HAVE_PTHREADS

int  evthread_use_pthreads(void);

#define EVTHREAD_USE_PTHREADS_IMPLEMENTED

#endif

以上函数在成功时返回0，失败是返回-1。

如果需要使用其他的多线程库，那么需要做一些额外的工作，你需要定义函数来实现下列机制：

锁、加锁、解锁、分配锁、销毁锁、条件变量、创建条件变量、销毁条件变量，等待条件变量、单播/广播条件变量、线程、线程ID监测。

然后，使用接口evthread_set_lock_callbacks和 evthread_set_id_callback 接口，告诉Libevent你要使用的函数：

#define EVTHREAD_WRITE  0x04

#define EVTHREAD_READ   0x08

#define EVTHREAD_TRY    0x10

#define  EVTHREAD_LOCKTYPE_RECURSIVE   1

#define  EVTHREAD_LOCKTYPE_READWRITE   2

#define  EVTHREAD_LOCK_API_VERSION    1

struct evthread_lock_callbacks{

int  lock_api_version;

unsigned  supported_locktypes;

void  *(*alloc)(unsigned locktype);

void  (*free)(void *lock, unsignedlocktype);

int  (*lock)(unsigned mode, void *lock);

int  (*unlock)(unsigned mode, void*lock);

};

int  evthread_set_lock_callbacks(const struct evthread_lock_callbacks *);

void  evthread_set_id_callback(unsigned long (*id_fn)(void));

struct  evthread_condition_callbacks {

int condition_api_version;

void *(*alloc_condition)(unsigned  condtype);

void (*free_condition)(void * cond);

int (*signal_condition)(void *cond, int  broadcast);

int (*wait_condition)(void * cond, void*  lock,

const struct timeval * timeout);

};

int  evthread_set_condition_callbacks(const  struct  evthread_condition_callbacks *);

evthread_lock_callbacks结构体描述了锁的性质。其中，lock_api_version必须置为EVTHREAD_LOCK_API_VERSION，supported_locktypes必须置为 EVTHREAD_LOCKTYPE_*常量的掩码来描述锁类型（在2.0.4-alpha版本中，EVTHREAD_LOCK_RECURSIVE是强制的，而EVTHREAD_LOCK_READWRITE是不能用的）。alloc函数必须能返回一个新的特定类型的锁对象。free函数必须能够释放特定类型的锁的所有资源。lock函数用来以特定的模式获得锁，返回0表示成功，非0表示失败。unlock函数用来解锁，返回0表示成功，非0表示失败。

锁类型包括：

0：常规的、非递归锁

EVTHREAD_LOCKTYPE_RECURSIVE：递归锁，允许同一个线程对其多次加锁，只有当前加锁的线程经过同样次数的解锁之后，其他线程才能够获得锁。

EVTHREAD_LOCKTYPE_READWRITE：读写锁，允许多个线程同时占有读模式的读写锁，但是同一时刻，只能有一个线程占有写模式的读写锁。一个写线程会阻塞所有读线程。

锁机制包括：

EVTHREAD_READ：读写锁特有，以读模式获得或释放读写锁

EVTHREAD_WRITE：读写锁特有，以写模式获得或释放读写锁

EVTHREAD_TRY：只有该锁可以立即获得时，才可以加锁。

id_fn参数是一个函数，该函数返回一个无符号长整型，该长整型用来区分调用该函数的线程。同一个线程必须返回同样的整数、同一时刻执行的不同线程必须返回不同的整数。

evthread_condition_callbacks结构体描述了条件变量的特性。lock_api_version必须置为EVTHREAD_CONDITION_API_VERSION。alloc_condition函数必须返回一个指向新的条件变量的指针。它接收0作为参数。free_condition函数释放条件变量所持有的资源。wait_condition函数有三个参数：由alloc_condition分配的条件变量、由evthread_lock_callbacks.alloc函数分配的锁，以及一个可选的超时参数。在该函数调用时，该锁必须已经加锁，该函数会释放该锁，然后等待条件变量的信号，或者超时时间到。wait_condition在出错时返回-1,返回0表示收到了条件变量的信号，返回1表示超时。在该函数返回时，该函数会重新加锁。

最后，如果signal_condition的broadcast 参数是false，该函数会唤醒一个等待条件变量的线程，如果broadcast 参数为True的话，所有等待条件变量的线程都会唤醒。只有在对与该条件变量相关的锁进行加锁之后，才能进行这些操作。

实例：参见evthread_pthread.c文件和evthread_win32.c文件

这些函数在<event2/thread.h>中声明，其中大多数在2.0.4-alpha版本中首次出现。2.0.1-alpha到2.0.3-alpha使用较老版本的锁函数。event_use_pthreads函数要求程序链接到event_pthreads库。

条件变量函数是2.0.7-rc版本新引入的，用于解决某些棘手的死锁问题。

构建libevent时，可以禁止锁支持。这时候已创建的使用上述线程相关函数的程序将不能运行。

五：锁调试的使用

为了能够对锁的使用进行调试，Libevent提供了“锁调试”的特性，它对锁调用进行了封装，从而可以捕捉到典型的锁错误，包括：解锁一个并没有加锁的锁；对一个非递归锁重新加锁。

如果发生了锁错误，Libevent将会以一个断言失败而退出。

void  evthread_enable_lock_debugging(void);

#define  evthread_enable_lock_debuging()  evthread_enable_lock_debugging()

该函数必须在任何锁创建和使用之前进行调用。安全起见，在设置线程函数之后调用。

六：事件调试的使用

在使用events时，Libevent可以检测并报告一些一般性的错误，包括：将一个未初始化的event当做已经初始化的event使用；对处于pending状态的event重新初始化。

因为跟踪哪个event被初始化需要额外的内存和CPU，所以应该仅调试程序时才使能调试模式。

void  event_enable_debug_mode(void);

该函数必须在任何event_base创建之前调用。

在debug模式下，如果程序用event_assign(不是event_new)创建了大量的events，那么有可能会将内存耗尽。这是因为Libevent没有办法知道由event_assign创建的event何时不再使用（对于event_new创建的event，当你调用event_free时，该event就会变为无效的了）。如果想要避免在调试模式下耗尽内存，可以明确地告诉Libevent，该event已经无效了：

void  event_debug_unassign(structevent *ev);

注意：如果没有使能调试模式，那么调用event_debug_unassign无效。

实例：

#include  <event2/event.h>

#include <event2/event_struct.h>

#include <stdlib.h>

void cb(evutil_socket_t fd, short what, void *ptr)

{

/* We pass 'NULL' as the callback pointer  for the heap allocated

* event, and we pass the event itself as  the callback pointer

* for the stack-allocated event. */

struct event *ev = ptr;

if (ev)

event_debug_unassign(ev);

}

/* Here's a simple mainloop  that waits until fd1 and fd2 are both

* ready to read. */

void mainloop(evutil_socket_t  fd1, evutil_socket_t fd2, int debug_mode)

{

struct event_base *base;

struct event event_on_stack,*event_on_heap;

if (debug_mode)

event_enable_debug_mode();

base = event_base_new();

event_on_heap = event_new(base, fd1, EV_READ, cb, NULL);

event_assign(&event_on_stack, base, fd2, EV_READ, cb, &event_on_stack);

event_add(event_on_heap, NULL);

event_add(&event_on_stack, NULL);

event_base_dispatch(base);

event_free(event_on_heap);

event_base_free(base);

}

事件调试这种特性，只有在编译时使用"-DUSE_DEBUG"的CFLAGS环境变量才能进行使能。使用该标识后，任何编译连接Libevent的程序将会输出非常详尽的日志信息。这些日志包括但不限于：添加event，删除event，特定平台的事件通知信息。

这种特性不能通过API的调用进行开启或禁用。这些调试功能在Libevent2.0.4-alpha之后加入。

七：检测Libevent版本

如果希望检测当前使用的Libevent版本，可以调试时打印Libevent的版本信息；

#define  LIBEVENT_VERSION_NUMBER  0x02000300

#define  LIBEVENT_VERSION  "2.0.3-alpha"

const char*  event_get_version(void);

ev_uint32_t  event_get_version_number(void);

这些宏提供了Libevent库的编译时版本；而函数返回运行版本。注意，如果你是动态链接到Libevent的话，这些版本有可能是不同的。

可以以两种格式得到Libevent的版本：字节整型形式。

整型形式中，使用高字节代表主版本，第二个字节代表次版本，第三个字节代表补丁版本，最后一个字节表示发布状态，0表示发布版本，非0表示给定发布版本之后的开发系列版本。因此，对于2.0.1-alpha发布版本的Libevent，它的版本号是[02 00 01 00]，或者0x02000100。介于2.0.1-alpha 和 2.0.2-alpha之间的开发版本可能的版本号是[02 00 01 08]，或是 0x02000108.

#include  <event2/event.h>

#if  !defined(LIBEVENT_VERSION_NUMBER) || LIBEVENT_VERSION_NUMBER < 0x02000100

#error "This version ofLibevent is not supported; Get 2.0.1-alpha or later."

#endif

int

make_sandwich(void)

{

/* Let's suppose that Libevent 6.0.5introduces a make-me-a

sandwich function. */

#if  LIBEVENT_VERSION_NUMBER>= 0x06000500

evutil_make_me_a_sandwich();

return 0;

#else

return -1;

#endif

}

Example: Run-time checks

#include <event2/event.h>

#include <string.h>

int

check_for_old_version(void)

{

const char *v = event_get_version();

/* This is a dumb way to do it, but it isthe only thing that works

before Libevent 2.0. */

if (!strncmp(v, "0.", 2) ||

!strncmp(v, "1.1", 3) ||

!strncmp(v, "1.2", 3) ||

!strncmp(v, "1.3", 3)) {

printf("Your version of Libeventis very old.  If you run into bugs,"

" consider  upgrading.\n");

return -1;

} else {

printf("Running with Libevent  version %s\n", v);

return 0;

}

}

int

check_version_match(void)

{

ev_uint32_t  v_compile, v_run;

v_compile = LIBEVENT_VERSION_NUMBER;

v_run = event_get_version_number();

if ((v_compile & 0xffff0000) != (v_run& 0xffff0000)) {

printf("Running with a Libevent  version (%s) very different from the "

"one we were built with(%s).\n", event_get_version(),

LIBEVENT_VERSION);

return -1;

}

return 0;

}

这些宏和函数定义在<event2/event.h>文件中。

八：释放Libevent全局结构

即使你已经释放了所有Libevent分配的对象，依然会残留一些全局分配的结构。一般来说这不会有问题：一旦程序退出了，所有资源都会被清理。但是，保留这些全局结构可能会使一些调试工具认为Libevent有内存泄露。如果希望Libevent释放所有内部“库全局”数据结构的话，需要调用：

void  libevent_global_shutdown(void);

注意，该函数不会释放任何Libevent返回给你的结构体。你若希望退出之前释放所有内存，则必须亲自释放所有的events,
event_bases，bufferevents等。

调用libevent_global_shutdown()会使其他的Libevent函数变得不可预知。所以该函数应该作为最后一个调用的Libevent函数。不过该函数具有幂等性，可以多次调用。（幂等性是说一个操作不管是执行一次还是多次，产生的副作用是一样的。幂等性是系统的接口对外一种承诺(而不是实现),
承诺只要调用接口成功, 外部多次调用对系统的影响是一致的。）

该函数在<event2/event.h>中声明。

原文：http://www.wangafu.net/~nickm/libevent-book/Ref1_libsetup.html