libevent_structure

struct event_config_entry

libevent 中的事件配置项。

通过使用 event_config_entry 结构体，可以在 libevent 中定义和管理多个事件配置项，并按照链表的方式进行链接和访问。每个配置项都包含一个要避免使用的网络通信方法

struct event_config_entry {
	TAILQ_ENTRY(event_config_entry) next;

	const char *avoid_method;//要避免使用的网络通信方法。
};

TAILQ_ENTRY 见：[[Macro function]]

struct event_base

struct event_base {
	//一个指向特定于后端数据的指针，用于描述这个event_base端。
	const struct eventop *evsel;
	//一个指向特定于后端数据的指针，用于指向底层事件驱动后端的实现。
	void *evbase;

	/** List of changes to tell backend about at next dispatch.  Only used
	 * by the O(1) backends. */
    
    //一个结构体，用于描述在下次调度时需要通知后端更改的事件
	struct event_changelist changelist;
	
	/** Function pointers used to describe the backend that this event_base
	 * uses for signals */
    
    //一个指向特定于信号处理后端数据的指针，用于描述后端event_base*用于信号处理。
	const struct eventop *evsigsel;
    
	/** Data to implement the common signal handler code. */
    //一个结构体，用于实现信号处理通用代码的数据。
	struct evsig_info sig;

	/** Number of virtual events */
    //用于表示当前虚拟事件数量。
	int virtual_event_count;
    
	/** Maximum number of virtual events active */
    //用于表示最大虚拟事件数量。
	int virtual_event_count_max;
    
	/** Number of total events added to this event_base */
    //用于表示已添加到event_base的事件数量。
	int event_count;
    
	/** Maximum number of total events added to this event_base */
    //用于表示最大已添加到event_base的事件数量。
	int event_count_max;
    
	/** Number of total events active in this event_base */
    //用于表示当前活动事件数量。
	int event_count_active;
    
	/** Maximum number of total events active in this event_base */
    //用于表示最大活动事件数量。
	int event_count_active_max;

	/** Set if we should terminate the loop once we're done processing
	 * events. */
    //用于表示是否应该在处理完事件后终止循环。
	int event_gotterm;
    
	/** Set if we should terminate the loop immediately */
	
    //用于表示是否应该立即终止循环。
	int event_break;
    
	/** Set if we should start a new instance of the loop immediately. */
    //用于表示是否应该在处理完事件后继续执行循环。
	int event_continue;

	/** The currently running priority of events */
    //用于表示当前正在运行的事件优先级。
	int event_running_priority;

	/** Set if we're running the event_base_loop function, to prevent
	 * reentrant invocation. */
    //用于表示是否正在运行event_base_loop函数，以防止重入调用。
	int running_loop;

	/** Set to the number of deferred_cbs we've made 'active' in the
	 * loop.  This is a hack to prevent starvation; it would be smarter
	 * to just use event_config_set_max_dispatch_interval's max_callbacks
	 * feature */
    //用于表示已 deferred_cbs 数量
	int n_deferreds_queued;

	/* Active event management. */
	/** An array of nactivequeues queues for active event_callbacks (ones
	 * that have triggered, and whose callbacks need to be called).  Low
	 * priority numbers are more important, and stall higher ones.
	 */
    //用于存储活动事件队列。
	struct evcallback_list *activequeues;
	/** The length of the activequeues array */
	int nactivequeues;//用于表示活动事件队列的数量。
	/** A list of event_callbacks that should become active the next time
	 * we process events, but not this time. */
    //于存储应该在下次处理事件时激活的事件。
	struct evcallback_list active_later_queue;

	/* common timeout logic */

	/** An array of common_timeout_list* for all of the common timeout
	 * values we know. */
    //用于存储所有已知的时间outs。
	struct common_timeout_list **common_timeout_queues;

    /** The number of entries used in common_timeout_queues */
    //用于表示已使用的时间outs数量。
	int n_common_timeouts;
    
	/** The total size of common_timeout_queues. */
    //用于表示已分配的时间outs数量。
	int n_common_timeouts_allocated;

	/** Mapping from file descriptors to enabled (added) events */
    //用于存储文件描述符到已添加事件的映射。
	struct event_io_map io;

	/** Mapping from signal numbers to enabled (added) events. */
    //用于存储信号编号到已添加事件的映射。
	struct event_signal_map sigmap;

	/** Priority queue of events with timeouts. */
    //1个优先队列，用于存储具有超时的事件。
	struct min_heap timeheap;

	/** Stored timeval: used to avoid calling gettimeofday/clock_gettime
	 * too often. */
    //用于存储当前时间，以避免频繁调用gettimeofday/clock_gettime。
	struct timeval tv_cache;
	
    //，用于实现单调时钟。
	struct evutil_monotonic_timer monotonic_timer;

	/** Difference between internal time (maybe from clock_gettime) and
	 * gettimeofday. */
    //用于存储内部时间与gettimeofday之间的差异。
	struct timeval tv_clock_diff;
    
	/** Second in which we last updated tv_clock_diff, in monotonic time. */
    //用于存储上次更新tv_clock_diff时的单调时间。
	time_t last_updated_clock_diff;

#ifndef EVENT__DISABLE_THREAD_SUPPORT
	/* threading support */
	/** The thread currently running the event_loop for this base */
	unsigned long th_owner_id;
	/** A lock to prevent conflicting accesses to this event_base */
	void *th_base_lock;
	/** A condition that gets signalled when we're done processing an
	 * event with waiters on it. */
	void *current_event_cond;
	/** Number of threads blocking on current_event_cond. */
	int current_event_waiters;
#endif
	/** The event whose callback is executing right now */
	struct event_callback *current_event;

#ifdef _WIN32
	/** IOCP support structure, if IOCP is enabled. */
    /**：一个指向`event_iocp_port`结构体的指针，如果在Windows平台上使用IOCP（I/O Completion Port）作为事件驱动后端，则使用此字段。
*/
	struct event_iocp_port *iocp;
#endif

	/** Flags that this base was configured with */
    //`flags`：一个枚举类型，用于表示`event_base`的配置标志。
    
	enum event_base_config_flag flags;
	
    //，用于表示最大调度时间。
	struct timeval max_dispatch_time;
    
	int max_dispatch_callbacks;//用于表示最大调度回调数量。
	int limit_callbacks_after_prio;//用于表示在达到特定优先级后限制回调数量。

	/* Notify main thread to wake up break, etc. */
	/** True if the base already has a pending notify, and we don't need
	 * to add any more. */
	int is_notify_pending;//用于表示`event_base`是否已经有一个待处理的通知。
	/** A socketpair used by some th_notify functions to wake up the main
	 * thread. */
    
    //用于free base
	evutil_socket_t th_notify_fd[2];//一个套接字对，用于在另一个线程中唤醒主线程。
	/** An event used by some th_notify functions to wake up the main
	 * thread. */
    
	struct event th_notify;//用于在主线程中唤醒其他线程。

	/** A function used to wake up the main thread from another thread. */
    /**`th_notify`：一个`event`结构体，用于在主线程中唤醒其他线程。*/
	int (*th_notify_fn)(struct event_base *base);

	/** Saved seed for weak random number generator. Some backends use
	 * this to produce fairness among sockets. Protected by th_base_lock. */
    //一个`evutil_weakrand_state`结构体，用于存储弱随机数生成器的种子。
	struct evutil_weakrand_state weakrand_seed;

	/** List of event_onces that have not yet fired. */
    /**`once_events`：一个`LIST_HEAD`结构体，用于存储尚未触发的事件。*/
	LIST_HEAD(once_event_list, event_once) once_events;

};

struct eventop

/** 用于定义给定事件基础结构的后端的结构体。 */

struct eventop {
    /** 后端的名称。 */
    const char *name;

    /** 初始化函数，用于设置事件基础结构以使用该后端。它应该创建一个新的结构体，
     * 保存运行该后端所需的任何信息，并将其返回。返回的指针将由event_init存储在
     * event_base.evbase字段中。如果初始化失败，该函数应返回NULL。 */
    void *(*init)(struct event_base *);

    /** 启用给定文件描述符或信号的读写事件。'events'参数表示我们要启用的事件类型，
     * 可能是EV_READ、EV_WRITE、EV_SIGNAL和EV_ET的组合。'old'参数表示之前在该
     * 文件描述符上启用的事件。'fdinfo'参数是与文件描述符相关联的结构体，在evmap
     * 中管理；其大小由下面的fdinfo_len字段定义。第一次添加文件描述符时，
     * 它将被设置为0。该函数应在成功时返回0，在错误时返回-1。 */
    int (*add)(struct event_base *, evutil_socket_t fd, short old, short events, void *fdinfo);

    /** 类似于'add'函数，但'events'参数表示我们要禁用的事件类型。 */
    int (*del)(struct event_base *, evutil_socket_t fd, short old, short events, void *fdinfo);

    /** 实现事件循环的核心功能。它需要检查哪些已添加的事件已准备就绪，并为每个活动事件
     * 调用event_active函数（通常通过event_io_active等方式）。该函数应在成功时返回0，
     * 在错误时返回-1。 */
    int (*dispatch)(struct event_base *, struct timeval *);

    /** 用于清理和释放事件基础结构中的数据的函数。 */
    void (*dealloc)(struct event_base *);

    /** 标志：如果我们在fork之后需要重新初始化事件基础结构，则设置此标志。 */
    int need_reinit;

    /** 支持的事件方法特性的位数组。 */
    enum event_method_feature features;

    /** 每个具有一个或多个活动事件的文件描述符应记录的额外信息的长度。
     * 此信息作为每个文件描述符的evmap条目的一部分记录，并作为参数传递给上述的
     * 'add'和'del'函数。 */
    size_t fdinfo_len;
};

struct event_config

/** Internal structure: describes the configuration we want for an event_base
 * that we're about to allocate. */
struct event_config {
    于定义一个双向链表的头部。它将被用作存储event_config_entry类型的结构体的链表。
	TAILQ_HEAD(event_configq, event_config_entry) entries;
    
    //用于提示事件配置所需的CPU数量。
	int n_cpus_hint;
    //指定最大分派间隔的时间值。
	struct timeval max_dispatch_interval;
    //指定在一次循环中最大的分派回调数量。
	int max_dispatch_callbacks;
    //用于限制在特定优先级之后的回调数量。
	int limit_callbacks_after_prio;
    //指定要求的事件方法特性。
    //event_config_require_featureEV_FEATURE_ET：要求支持边沿触发的后端等
	enum event_method_feature require_features;
    //指定事件基础配置的标志。
	enum event_base_config_flag flags;//event_config_set_flag 设置具体可用参数见上文
};

TAILQ_HEAD 见：[[Macro function]]

struct timeval

/* A time value that is accurate to the nearest

  microsecond but also has a range of years.  */

struct timeval

{

 __time_t tv_sec;   /* Seconds.  */

 __suseconds_t tv_usec;  /* Microseconds.  */

};

struct evbuffer

struct evbuffer {

    /** The first chain in this buffer's linked list of chains. */

    struct evbuffer_chain *first;

    /** The last chain in this buffer's linked list of chains. */

    struct evbuffer_chain *last;

  

    /** Pointer to the next pointer pointing at the 'last_with_data' chain.

     *

     * To unpack:

     *

     * The last_with_data chain is the last chain that has any data in it.

     * If all chains in the buffer are empty, it is the first chain.

     * If the buffer has no chains, it is NULL.

     *

     * The last_with_datap pointer points at _whatever 'next' pointer_

     * pointing at the last_with_data chain. If the last_with_data chain

     * is the first chain, or it is NULL, then the last_with_datap pointer

     * is &buf->first.

     */

    struct evbuffer_chain **last_with_datap;

  

    /** Total amount of bytes stored in all chains.*/

    size_t total_len;

  

    /** Number of bytes we have added to the buffer since we last tried to

     * invoke callbacks. */

    size_t n_add_for_cb;

    /** Number of bytes we have removed from the buffer since we last

     * tried to invoke callbacks. */

    size_t n_del_for_cb;

  

#ifndef EVENT__DISABLE_THREAD_SUPPORT

    /** A lock used to mediate access to this buffer. */

    void *lock;

#endif

    /** True iff we should free the lock field when we free this

     * evbuffer. */

    unsigned own_lock : 1;

    /** True iff we should not allow changes to the front of the buffer

     * (drains or prepends). */

    unsigned freeze_start : 1;

    /** True iff we should not allow changes to the end of the buffer

     * (appends) */

    unsigned freeze_end : 1;

    /** True iff this evbuffer's callbacks are not invoked immediately

     * upon a change in the buffer, but instead are deferred to be invoked

     * from the event_base's loop.  Useful for preventing enormous stack

     * overflows when we have mutually recursive callbacks, and for

     * serializing callbacks in a single thread. */

    unsigned deferred_cbs : 1;

#ifdef _WIN32

    /** True iff this buffer is set up for overlapped IO. */

    unsigned is_overlapped : 1;

#endif

    /** Zero or more EVBUFFER_FLAG_* bits */

    ev_uint32_t flags;

  

    /** Used to implement deferred callbacks. */

    struct event_base *cb_queue;

  

    /** A reference count on this evbuffer.  When the reference count

     * reaches 0, the buffer is destroyed.  Manipulated with

     * evbuffer_incref and evbuffer_decref_and_unlock and

     * evbuffer_free. */

    int refcnt;

  

    /** A struct event_callback handle to make all of this buffer's callbacks

     * invoked from the event loop. */

    struct event_callback deferred;

  

    /** A doubly-linked-list of callback functions */

    LIST_HEAD(evbuffer_cb_queue, evbuffer_cb_entry) callbacks;

  

    /** The parent bufferevent object this evbuffer belongs to.

     * NULL if the evbuffer stands alone. */

    struct bufferevent *parent;

};

struct bufferevent

struct bufferevent {

    /** Event base for which this bufferevent was created. */

    struct event_base *ev_base;

    /** Pointer to a table of function pointers to set up how this

        bufferevent behaves. */

    const struct bufferevent_ops *be_ops;

  

    /** A read event that triggers when a timeout has happened or a socket

        is ready to read data.  Only used by some subtypes of

        bufferevent. */

    struct event ev_read;

    /** A write event that triggers when a timeout has happened or a socket

        is ready to write data.  Only used by some subtypes of

        bufferevent. */

    struct event ev_write;

  

    /** An input buffer. Only the bufferevent is allowed to add data to

        this buffer, though the user is allowed to drain it. */

    struct evbuffer *input;

  

    /** An input buffer. Only the bufferevent is allowed to drain data

        from this buffer, though the user is allowed to add it. */

    struct evbuffer *output;

  

    struct event_watermark wm_read;

    struct event_watermark wm_write;

  

    bufferevent_data_cb readcb;

    bufferevent_data_cb writecb;

    /* This should be called 'eventcb', but renaming it would break

     * backward compatibility */

    bufferevent_event_cb errorcb;

    void *cbarg;

  

    struct timeval timeout_read;

    struct timeval timeout_write;

  

    /** Events that are currently enabled: currently EV_READ and EV_WRITE

        are supported. */

    short enabled;

};

• ev_base:

  • 指向 event_base 结构体，表示 bufferevent 所关联的事件基础设施。

• be_ops:

  • 指向 bufferevent_ops 结构体的指针，用于操作 bufferevent 的行为（如读写操作的具体实现）。

• ev_read:

  • struct event 类型的字段，用于处理读事件。这是一个底层的事件，用于监视文件描述符是否可读，或者监视超时事件。

• ev_write:

  • struct event 类型的字段，用于处理写事件。这也是一个底层的事件，用于监视文件描述符是否可写，或者监视超时事件。

• input:

  • 指向 evbuffer 结构体的指针，作为输入缓冲区。bufferevent 负责将数据添加到此缓冲区，而用户可以从中读取数据。

• output:

  • 指向 evbuffer 结构体的指针，作为输出缓冲区。bufferevent 负责从此缓冲区读取数据，而用户可以将数据写入该缓冲区。

• wm_read 和 wm_write:

  • event_watermark 结构体，定义了读写操作的水印值，用于控制在何时触发读或写事件。

• readcb 和 writecb:

  • 回调函数，用于处理读写操作。当数据可读或可写时，这些回调函数会被调用。

• errorcb:

  • 错误回调函数，用于处理 bufferevent 发生错误的情况。为了兼容性，虽然应该命名为 eventcb，但保留了旧名称。

• cbarg:

  • 指向用户定义的数据的指针，这些数据会传递给回调函数。

• timeout_read 和 timeout_write:

  • struct timeval 类型的字段，定义了读写操作的超时时间。用于在读取或写入操作超时时触发相应的事件。

• enabled:

  • 记录当前启用的事件类型。可以是 EV_READ、EV_WRITE 或它们的组合。

• 这个结构体用于 libevent 中的缓冲事件处理机制，使得你可以处理异步的 I/O 操作，同时管理数据的读写缓冲区。

struct bufferevent_private

  

/** Parts of the bufferevent structure that are shared among all bufferevent

 * types, but not exposed in bufferevent_struct.h. */

struct bufferevent_private {

    /** The underlying bufferevent structure. */

    struct bufferevent bev;

  

    /** Evbuffer callback to enforce watermarks on input. */

    struct evbuffer_cb_entry *read_watermarks_cb;

  

    /** If set, we should free the lock when we free the bufferevent. */

    unsigned own_lock : 1;

  

    /** Flag: set if we have deferred callbacks and a read callback is

     * pending. */

    unsigned readcb_pending : 1;

    /** Flag: set if we have deferred callbacks and a write callback is

     * pending. */

    unsigned writecb_pending : 1;

    /** Flag: set if we are currently busy connecting. */

    unsigned connecting : 1;

    /** Flag: set if a connect failed prematurely; this is a hack for

     * getting around the bufferevent abstraction. */

    unsigned connection_refused : 1;

    /** Set to the events pending if we have deferred callbacks and

     * an events callback is pending. */

    short eventcb_pending;

  

    /** If set, read is suspended until one or more conditions are over.

     * The actual value here is a bitfield of those conditions; see the

     * BEV_SUSPEND_* flags above. */

    bufferevent_suspend_flags read_suspended;

  

    /** If set, writing is suspended until one or more conditions are over.

     * The actual value here is a bitfield of those conditions; see the

     * BEV_SUSPEND_* flags above. */

    bufferevent_suspend_flags write_suspended;

  

    /** Set to the current socket errno if we have deferred callbacks and

     * an events callback is pending. */

    int errno_pending;

  

    /** The DNS error code for bufferevent_socket_connect_hostname */

    int dns_error;

  

    /** Used to implement deferred callbacks */

    struct event_callback deferred;

  

    /** The options this bufferevent was constructed with */

    enum bufferevent_options options;

  

    /** Current reference count for this bufferevent. */

    int refcnt;

  

    /** Lock for this bufferevent.  Shared by the inbuf and the outbuf.

     * If NULL, locking is disabled. */

    void *lock;

  

    /** No matter how big our bucket gets, don't try to read more than this

     * much in a single read operation. */

    ev_ssize_t max_single_read;

  

    /** No matter how big our bucket gets, don't try to write more than this

     * much in a single write operation. */

    ev_ssize_t max_single_write;

  

    /** Rate-limiting information for this bufferevent */

    struct bufferevent_rate_limit *rate_limiting;

  

    /* Saved conn_addr, to extract IP address from it.

     *

     * Because some servers may reset/close connection without waiting clients,

     * in that case we can't extract IP address even in close_cb.

     * So we need to save it, just after we connected to remote server, or

     * after resolving (to avoid extra dns requests during retrying, since UDP

     * is slow) */

    union {

        struct sockaddr_in6 in6;

        struct sockaddr_in in;

    } conn_address;

  

    struct evdns_getaddrinfo_request *dns_request;

};

bufferevent_private 结构体是 bufferevent 结构体的一个扩展部分，包含了用于实现 bufferevent 的私有数据和状态。这些成员在 bufferevent_struct.h 头文件中并未暴露，旨在实现封装和内部管理。

• struct bufferevent bev:

  • 这是 bufferevent 结构体的基础部分。bufferevent_private 通过包含 bufferevent 结构体，继承了 bufferevent 的所有公开接口和基本功能。

• struct evbuffer_cb_entry *read_watermarks_cb:

  • 用于处理输入缓冲区的watermarks回调。这是 evbuffer 结构体的回调机制的一部分，用于实现流量控制或其他与数据处理相关的逻辑。

• unsigned own_lock : 1:

  • 标记是否在释放 bufferevent 时需要释放锁。如果设置了该标志，则 bufferevent 的销毁过程将包括锁的释放。

• unsigned readcb_pending : 1 和 unsigned writecb_pending : 1:

  • 分别表示是否有待处理的读回调或写回调。这些标志用于处理延迟的回调函数，确保它们在适当的时间被调用。

• unsigned connecting : 1:

  • 指示当前是否正在进行连接操作。这有助于处理与连接状态相关的特殊情况。

• unsigned connection_refused : 1:

  • 标记连接是否被拒绝。这是为了绕过 bufferevent 抽象的一种技巧，用于处理连接失败的情况。

• short eventcb_pending:

  • 如果有延迟的回调并且事件回调待处理，这里保存待处理的事件。

• bufferevent_suspend_flags read_suspended 和 bufferevent_suspend_flags write_suspended:

  • 分别用于指示读取和写入操作是否被暂停。这里使用位域来表示不同的暂停条件。

• int errno_pending:

  • 保存当前待处理的 errno 错误码，以便在事件回调中使用。

• int dns_error:

  • 用于存储与 DNS 解析相关的错误码，特别是用于 bufferevent_socket_connect_hostname 的操作。

• struct event_callback deferred:

  • 用于实现延迟回调的机制，允许在特定条件满足时才执行回调函数。

• enum bufferevent_options options:

  • 存储创建 bufferevent 时使用的选项。这可以包括各种配置选项，如缓冲区大小、事件类型等。

• int refcnt:

  • 当前 bufferevent 的引用计数，用于管理内存和资源的生命周期。

• void *lock:

  • 指向用于保护 bufferevent 结构体中共享资源的锁。如果为 NULL，则表示锁定机制被禁用。

• ev_ssize_t max_single_read 和 ev_ssize_t max_single_write:

  • 限制单次读取或写入操作的最大字节数，以避免在处理大数据量时出现性能问题或其他潜在问题。

• struct bufferevent_rate_limit *rate_limiting:

  • 用于实现速率限制的结构体，控制数据的传输速率。

• union { struct sockaddr_in6 in6; struct sockaddr_in in; } conn_address:

  • 保存连接地址，用于从服务器获取 IP 地址，即使在连接关闭时也能保留该信息。

• struct evdns_getaddrinfo_request *dns_request:

  • 用于 DNS 查询的请求结构体，协助处理域名解析过程。

• bufferevent_private 结构体封装了 bufferevent 结构体的实现细节，包括锁、缓冲区、水位、延迟回调、速率限制等。这种设计使得 bufferevent 的内部实现与对外接口隔离，提高了代码的模块化和可维护性，同时也提供了更强大的功能来处理网络事件和数据流

struct bufferevent_ops

bufferevent_ops 结构体定义了与 bufferevent 类型相关的操作表，用于处理不同类型的 bufferevent 实现。这种设计使得 bufferevent 可以有多个不同的实现类型，每种类型都有自己专门的操作函数

struct bufferevent_ops {
	/** The name of the bufferevent's type. */
	const char *type;

	/** At what offset into the implementation type will we find a
	    bufferevent structure?

	    Example: if the type is implemented as
	    struct bufferevent_x {
	       int extra_data;
	       struct bufferevent bev;
	    }
	    then mem_offset should be offsetof(struct bufferevent_x, bev)
	*/
	off_t mem_offset;

	/** Enables one or more of EV_READ|EV_WRITE on a bufferevent.  Does
	    not need to adjust the 'enabled' field.  Returns 0 on success, -1
	    on failure.
	 */
	int (*enable)(struct bufferevent *, short);

	/** Disables one or more of EV_READ|EV_WRITE on a bufferevent.  Does
	    not need to adjust the 'enabled' field.  Returns 0 on success, -1
	    on failure.
	 */
	int (*disable)(struct bufferevent *, short);

	/** Detaches the bufferevent from related data structures. Called as
	 * soon as its reference count reaches 0. */
	void (*unlink)(struct bufferevent *);

	/** Free any storage and deallocate any extra data or structures used
	    in this implementation. Called when the bufferevent is
	    finalized.
	 */
	void (*destruct)(struct bufferevent *);

	/** Called when the timeouts on the bufferevent have changed. */
	int (*adj_timeouts)(struct bufferevent *);

	/** Called to flush data. */
	int (*flush)(struct bufferevent *, short, enum bufferevent_flush_mode);

	/** Called to access miscellaneous fields. */
	int (*ctrl)(struct bufferevent *, enum bufferevent_ctrl_op, union bufferevent_ctrl_data *);
};

• const char *type:

  • 这是一个指向字符的指针，用于描述 bufferevent 类型的名称。例如，可以是 "socket", "filter", 或 "pair"。

• off_t mem_offset:

  • 表示 bufferevent 结构体在具体实现中的偏移量。这有助于在实际结构体中找到 bufferevent 结构体的位置。例如，如果 bufferevent 是结构体中的一部分，mem_offset 指定了它在结构体中的位置。

• int (*enable)(struct bufferevent *, short):

  • 函数指针，用于启用 EV_READ 或 EV_WRITE 事件。返回 0 表示成功，-1 表示失败。这个函数并不需要调整 enabled 字段的值。

• int (*disable)(struct bufferevent *, short):

  • 函数指针，用于禁用 EV_READ 或 EV_WRITE 事件。类似地，返回 0 表示成功，-1 表示失败。

• void (*unlink)(struct bufferevent *):

  • 函数指针，用于在 bufferevent 的引用计数达到 0 时，将其从相关数据结构中分离。这个函数在 bufferevent 的引用计数减少到零时被调用。

• void (*destruct)(struct bufferevent *):

  • 函数指针，用于释放 bufferevent 使用的任何额外存储或数据结构。这个函数在 bufferevent 被销毁时调用。

• int (*adj_timeouts)(struct bufferevent *):

  • 函数指针，用于调整 bufferevent 的超时设置。这个函数在 bufferevent 的超时设置发生变化时被调用。

• int (*flush)(struct bufferevent *, short, enum bufferevent_flush_mode):

  • 函数指针，用于刷新数据。根据提供的模式（bufferevent_flush_mode），该函数会将数据刷新到目标。

• int (*ctrl)(struct bufferevent *, enum bufferevent_ctrl_op, union bufferevent_ctrl_data *):

  • 函数指针，用于访问 bufferevent 的各种控制操作。这个函数允许对 bufferevent 进行特定的控制操作。

extern definition

extern const struct bufferevent_ops bufferevent_ops_socket;
extern const struct bufferevent_ops bufferevent_ops_filter;
extern const struct bufferevent_ops bufferevent_ops_pair;

这些是不同类型 bufferevent 的操作表的声明：

• bufferevent_ops_socket: 用于处理基于套接字的 bufferevent 实现。
• bufferevent_ops_filter: 用于处理过滤器类型的 bufferevent 实现。
• bufferevent_ops_pair: 用于处理配对类型的 bufferevent 实现。

macro definition

#define BEV_IS_SOCKET(bevp) ((bevp)->be_ops == &bufferevent_ops_socket)
#define BEV_IS_FILTER(bevp) ((bevp)->be_ops == &bufferevent_ops_filter)
#define BEV_IS_PAIR(bevp) ((bevp)->be_ops == &bufferevent_ops_pair)

这些宏用于检查给定的 bufferevent 是否为特定类型：

• BEV_IS_SOCKET(bevp): 判断 bufferevent 是否是套接字类型。
• BEV_IS_FILTER(bevp): 判断 bufferevent 是否是过滤器类型。
• BEV_IS_PAIR(bevp): 判断 bufferevent 是否是配对类型。

这些宏利用了 bufferevent 的操作表指针 be_ops，根据其是否匹配已知的类型操作表来判断 bufferevent 的类型。

union bufferevent_ctrl_data

bufferevent_ctrl_op

/** Possible operations for a control callback. */

enum bufferevent_ctrl_op {
    BEV_CTRL_SET_FD,       // 设置底层的文件描述符
    BEV_CTRL_GET_FD,       // 获取底层的文件描述符
    BEV_CTRL_GET_UNDERLYING, // 获取底层的 bufferevent
    BEV_CTRL_CANCEL_ALL    // 取消所有的回调
};
  

/** Possible data types for a control callback */

1. BEV_CTRL_SET_FD

• 描述：设置底层 bufferevent 的文件描述符。
• 用途：在某些实现中，底层的 bufferevent 可能需要设置一个新的文件描述符。此操作允许用户提供新的文件描述符。

2. BEV_CTRL_GET_FD

• 描述：获取底层 bufferevent 的文件描述符。
• 用途：用于检索底层 bufferevent 的文件描述符，通常用于获取当前 bufferevent 关联的套接字描述符。

3. BEV_CTRL_GET_UNDERLYING

• 描述：获取底层的 bufferevent 结构体。
• 用途：在实现中，bufferevent 可能会有多个层次的抽象或包装。此操作允许获取底层的实际 bufferevent 实现，从而进行更底层的操作或访问。

4. BEV_CTRL_CANCEL_ALL

• 描述：取消所有注册的回调。
• 用途：用于取消所有待处理的回调函数。此操作通常用于在某些情况下需要清除所有挂起的回调，以防止它们在未来被执行。

bufferevent_ctrl_data

union bufferevent_ctrl_data {

    void *ptr;

    evutil_socket_t fd;

};

struct evbuffer_chain

  

/** A single item in an evbuffer. */

struct evbuffer_chain {

    /** points to next buffer in the chain */

    struct evbuffer_chain *next;

  

    /** total allocation available in the buffer field. */

    size_t buffer_len;

  

    /** unused space at the beginning of buffer or an offset into a

     * file for sendfile buffers. */

    ev_misalign_t misalign;

  

    /** Offset into buffer + misalign at which to start writing.

     * In other words, the total number of bytes actually stored

     * in buffer. */

    size_t off;

  

    /** Set if special handling is required for this chain */

    unsigned flags;

#define EVBUFFER_FILESEGMENT    0x0001  /**< A chain used for a file segment */

#define EVBUFFER_SENDFILE   0x0002  /**< a chain used with sendfile */

#define EVBUFFER_REFERENCE  0x0004  /**< a chain with a mem reference */

#define EVBUFFER_IMMUTABLE  0x0008  /**< read-only chain */

    /** a chain that mustn't be reallocated or freed, or have its contents

     * memmoved, until the chain is un-pinned. */

#define EVBUFFER_MEM_PINNED_R   0x0010

#define EVBUFFER_MEM_PINNED_W   0x0020

#define EVBUFFER_MEM_PINNED_ANY (EVBUFFER_MEM_PINNED_R|EVBUFFER_MEM_PINNED_W)

    /** a chain that should be freed, but can't be freed until it is

     * un-pinned. */

#define EVBUFFER_DANGLING   0x0040

    /** a chain that is a referenced copy of another chain */

#define EVBUFFER_MULTICAST  0x0080

  

    /** number of references to this chain */

    int refcnt;

  

    /** Usually points to the read-write memory belonging to this

     * buffer allocated as part of the evbuffer_chain allocation.

     * For mmap, this can be a read-only buffer and

     * EVBUFFER_IMMUTABLE will be set in flags.  For sendfile, it

     * may point to NULL.

     */

    unsigned char *buffer;

};

• struct evbuffer_chain *next:

  • 描述：指向链表中下一个 evbuffer_chain 节点的指针。
  • 作用：允许多个 evbuffer_chain 节点通过链表结构连接在一起，从而管理整个缓冲区的数据。

• size_t buffer_len:

  • 描述：表示 buffer 字段中总的可用分配空间的大小。
  • 作用：确定当前链条可以容纳多少数据。

• ev_misalign_t misalign:

  • 描述：表示 buffer 开始位置前的未使用空间，或者在发送文件缓冲区时的文件偏移量。
  • 作用：用于处理缓冲区起始位置的对齐问题，或者在使用 sendfile 时，表示文件内容的起始位置。

• size_t off:

  • 描述：表示从 buffer 开始位置加上 misalign 后可以开始写入的偏移量，或者已经存储在 buffer 中的字节数。
  • 作用：指示当前链条中实际存储数据的结束位置。

• unsigned flags:

  • 描述：用于设置链条的特殊处理标志。
  • 作用：通过标志字段指定链条的不同属性或行为，例如是否用于文件片段、是否是只读链条等。
  • 具体标志：
    • EVBUFFER_FILESEGMENT：表示链条用于文件片段。
    • EVBUFFER_SENDFILE：表示链条与 sendfile 函数一起使用。
    • EVBUFFER_REFERENCE：表示链条包含内存引用。
    • EVBUFFER_IMMUTABLE：表示链条是只读的。
    • EVBUFFER_MEM_PINNED_R：表示链条在读时被固定，不能重新分配或释放。
    • EVBUFFER_MEM_PINNED_W：表示链条在写时被固定，不能重新分配或释放。
    • EVBUFFER_DANGLING：表示链条应该被释放，但不能立即释放，直到解除固定。
    • EVBUFFER_MULTICAST：表示链条是另一个链条的引用副本。

• int refcnt:

  • 描述：表示对当前链条的引用计数。
  • 作用：用于跟踪链条的引用数，以便正确管理内存（例如在链条被销毁之前，确保所有引用都被清除）。

• unsigned char *buffer:

  • 描述：通常指向实际的读写内存，属于当前 evbuffer_chain 分配的一部分。
  • 作用：用于存储实际的数据。对于使用 mmap 的情况，它可能是只读的，并且会设置 EVBUFFER_IMMUTABLE 标志。对于 sendfile，它可能指向 NULL，因为数据可能在文件中，而不是在内存中。