libevent源码event_new，event_add，evbuffer_remove，evbuffer_add

/**
  Allocate and asssign a new event structure, ready to be added.
  分配并指定一个新的event结构体，这个结构体将被添加。
  The function event_new() returns a new event that can be used in
  future calls to event_add() and event_del().  The fd and events
  arguments determine which conditions will trigger the event; the
  callback and callback_arg arguments tell Libevent what to do when the
  event becomes active.
　　函数event_new()返回一个新的event，它在后续的event_add()和event_del()中被用到。fd
和events参数决定了事件被触发的条件；回调和回调参数告诉libevent干什么，什么时候事件转换成活动的


  If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then
  fd is a file descriptor or socket that should get monitored for
  readiness to read, readiness to write, or readiness for either operation
  (respectively).  If events contains EV_SIGNAL, then fd is a signal
  number to wait for.  If events contains none of those flags, then the
  event can be triggered only by a timeout or by manual activation with
  event_active(): In this case, fd must be -1.
　　如果events包含了EV_READ,EV_WRITE,或者EV_READ|EV_WRITE中一个，那么作为一个文件描叙符或者套接字的fd
应该被监控准备好读，准备好写，或者准备任意一种操作（分别）。如果events包含EV_SIGNAL, fd是个要等待的信号数。
如果events不包含上面说的任意一个标识，那么只有超时或者手动调用event_active()激活来触发事件：在这种情况下，
fd 必须设置为-1。


  The EV_PERSIST flag can also be passed in the events argument: it makes
  event_add() persistent until event_del() is called.
　　　EV_PERSIST,让event_add()持续到event_del()被调用。　event_add(),是用于将事件添加到未决事件集合中；
当使用了EV_PERSIST，那么事件被添加到未决事件集合后，其未决事件这一状态将会被保持。

  The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported
  only by certain backends.  It tells Libevent to use edge-triggered
  events.
　　EV_ET是EV_READ和EV_WRITE兼容，仅支持某些后端。它告诉libevent使用边缘触发事件。


  The EV_TIMEOUT flag has no effect here.
　　EV_TIMEOUT没有影响。

  It is okay to have multiple events all listening on the same fds; but
  they must either all be edge-triggered, or all not be edge triggerd.

  When the event becomes active, the event loop will run the provided
  callbuck function, with three arguments.  The first will be the provided
  fd value.  The second will be a bitfield of the events that triggered:
  EV_READ, EV_WRITE, or EV_SIGNAL.  Here the EV_TIMEOUT flag indicates
  that a timeout occurred, and EV_ET indicates that an edge-triggered
  event occurred.  The third event will be the callback_arg pointer that
  you provide.

  @param base the event base to which the event should be attached. base，事件将被添加给这个base
  @param fd the file descriptor or signal to be monitored, or -1. 被监控的文件描叙符或者信号，或者-1
  @param events desired events to monitor: bitfield of EV_READ, EV_WRITE,
      EV_SIGNAL, EV_PERSIST, EV_ET. 期望监控的事件：EV_READ, EV_WRITE, EV_SIGNAL, EV_PERSIST, EV_ET
  @param callback callback function to be invoked when the event occurs 当事件发生时被触发的回调函数
  @param callback_arg an argument to be passed to the callback function 一个被传递给回调函数的参数

  @return a newly allocated struct event that must later be freed with
    event_free(). 一个新分配的事件结构，在后续必须通过event_free()释放
  @see event_free(), event_add(), event_del(), event_assign()
 */

struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *);

　　

/**
  Add an event to the set of pending events.
　　将一个事件添加到未决事件中

  The function event_add() schedules the execution of the event 'ev' when the
  condition specified by event_assign() or event_new() occurs, or when the time
  specified in timeout has elapesed.  If atimeout is NULL, no timeout
  occurs and the function will only be
  called if a matching event occurs.  The event in the
  ev argument must be already initialized by event_assign() or event_new()
  and may not be used
  in calls to event_assign() until it is no longer pending.
　　当event_assign()或者event_new()指定的条件触发了，或者指定的超时发生了，函数event_add()决定事件‘ev’的执行。
　　如果超时为空，表示没有超时发生，并且函数仅仅在符合事件发生时才会被调用。
　　ev参数里的事件必须已经被event_assign()或者event_new()初始化，
　　在它转换成未决定前，调用event_assign()时可能不会被使用ev。

  If the event in the ev argument already has a scheduled timeout, calling
  event_add() replaces the old timeout with the new one if tv is non-NULL.
　　如果ev参数里的event已经有了一个设定的超时，而这时tv又非空，调用event_add()，使用新的替换旧的超时

  @param ev an event struct initialized via event_assign() or event_new() 一个通过event_assign()或者event_new()初始化的事件结构体
  @param timeout the maximum amount of time to wait for the event, or NULL
         to wait forever 等待事件的最大时间值，或者NULL（一直等待事件）
  @return 0 if successful, or -1 if an error occurred 成功0， 错误-1
  @see event_del(), event_assign(), event_new()
  */

int event_add(struct event *ev, const struct timeval *timeout);

　　

/**
  Read data from an evbuffer and drain the bytes read.
　　从evbuffer中读取数据并清空读取的字节数

  If more bytes are requested than are available in the evbuffer, we
  only extract as many bytes as were available.
　　如果请求的字节数超过了evbuffer里可读字节数，只提供尽可能多的字节。

  @param buf the evbuffer to be read from 将被读取的evbuffer
  @param data the destination buffer to store the result 目标buffer，用来存放数据
  @param datlen the maximum size of the destination buffer 目标buffer的最大容量
  @return the number of bytes read, or -1 if we can't drain the buffer. 读取的字节数，如果无法清空数据，返回-1
 */

int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);

　　

/**
  Append data to the end of an evbuffer.
　　添加数据到evbuffer末尾

  @param buf the evbuffer to be appended to 添加到evbuffer的buf
  @param data pointer to the beginning of the data buffer 指向数据缓存区的开始
  @param datlen the number of bytes to be copied from the data buffer 从数据缓存中拷贝的字节数
  @return 0 on success, -1 on failure. 0成功，-1失败
 */

int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);

　　

/**
  Prepare a new, already-allocated event structure to be added.
　　准备一个新的，已分配好的event结构体，用于添加

  The function event_assign() prepares the event structure ev to be used
  in future calls to event_add() and event_del().  Unlike event_new(), it
  doesn't allocate memory itself: it requires that you have already
  allocated a struct event, probably on the heap.  Doing this will
  typically make your code depend on the size of the event structure, and
  thereby create incompatibility with future versions of Libevent.
　　函数event_assign()准备的event结构体将用于event_add()和event_del().和evetn_new(),
不同，它不为自己分配内存；它要求你已分配好一个event结构体，可能在堆上。这样做，会让代码依赖event
结构体的大小，从而导致与高版本的libevent不兼容。


  The easiest way to avoid this problem is just to use event_new() and
  event_free() instead.
　　避免这个问题的最简单的方法是使用event_new()和event_free()替换。

  A slightly harder way to future-proof your code is to use
  event_get_struct_event_size() to determine the required size of an event
  at runtime.
　　考虑到代码的拓展，相较麻烦点的方法是，使用event_get_struct_event_size()来获取event运行时的大小


  Note that it is NOT safe to call this function on an event that is
  active or pending.  Doing so WILL corrupt internal data structures in
  Libevent, and lead to strange, hard-to-diagnose bugs.  You _can_ use
  event_assign to change an existing event, but only if it is not active
  or pending!
　　对于活动的或是挂起的事件，调用这个杉树是不安全的。这样会导致libevent内部数据结构冲突，
并导致奇怪，难以诊断的bugs。当事件是非活动或者挂起的，可以使用event_assign()来改变一个已存在的事件。


  The arguments for this function, and the behavior of the events that it
  makes, are as for event_new().
　　这个函数的参数，及事件的行为，和event_new()一样.

  @param ev an event struct to be modified 将被定义的event结构体
  @param base the event base to which ev should be attached. base，ev将被附加到其上
  @param fd the file descriptor to be monitored 将被监视的文件描叙符
  @param events desired events to monitor; can be EV_READ and/or EV_WRITE 期望的监视事件
  @param callback callback function to be invoked when the event occurs 回调函数，当事件触发时，会被调用
  @param callback_arg an argument to be passed to the callback function 参数，传递给回调函数

  @return 0 if success, or -1 on invalid arguments. 0成功，-1失败

  @see event_new(), event_add(), event_del(), event_base_once(),
    event_get_struct_event_size()
  */

int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *);