Detailed explanation of nginx event module structure

Event module is one of the core modules of nginx. The processing of client requests and the execution of command line instructions in nginx are driven by the event module. Therefore, mastering the implementation principle of the event module is of great significance for us to understand the overall architecture of nginx.

##This article will first explain several module definitions related to the event module and its execution process, as well as its source code. Will be done in a later article.

Recommended tutorial:

Nginx tutorial

nginx mainly has two event core modules:

ngx_events_module and ngx_event_core_module. The main difference between these two modules is that the type of ngx_events_module is NGX_CORE_MODULE. Although it is essentially a core module type, it is a driving point of the event module. Its parsed configuration item is events {}. And a structure will be created to store the related configuration of the event module;

The type of ngx_event_core_module is

NGX_EVENT_MODULE. The basic configuration object of the event module will be stored in the configuration object of this module. The main function is to parse the sub-configuration items in the events{} configuration block.

Let’s take a look at the basic configuration of these two modules.

1. ngx_events_module

The following is the basic configuration of the ngx_events_module module:

ngx_module_t ngx_events_module = {
    NGX_MODULE_V1,
    &ngx_events_module_ctx,                /* module context */
    ngx_events_commands,                   /* module directives */
    NGX_CORE_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};
static ngx_core_module_t ngx_events_module_ctx = {
    ngx_string("events"),
    NULL,
    ngx_event_init_conf
};
static ngx_command_t ngx_events_commands[] = {
    {ngx_string("events"),
     NGX_MAIN_CONF | NGX_CONF_BLOCK | NGX_CONF_NOARGS,
     ngx_events_block,
     0,
     0,
     NULL},
    ngx_null_command
};

In the definition of the

ngx_events_module module, its The module context points to ngx_events_module_ctx, which is the configuration of the second structure, and the module directives points to ngx_events_commands, which is the definition of the third structure. It can be seen that only one events configuration item is defined in ngx_events_commands, and the type of this configuration item is NGX_CONF_BLOCK, which means that it is a configuration block type. Here we understand that this command corresponds to It is the events {} configuration block we use in nginx.conf, and the parsing of this configuration block is performed through the ngx_events_block() method.

We know that in the conf_ctx array in the nginx core configuration object ngx_cycle_t, each module will have a configuration object at the corresponding position of the array. Similarly, the core module here will also have a configuration object. But the second attribute value in the second structure

ngx_events_module_ctx above is NULL, which means that there is no method to create a configuration object in the definition of the event module here, but there is a way to initialize the configuration object. method, that is, the third attribute value ngx_event_init_conf() method.

So where is the configuration object of the event module created here?

In fact, it is performed when parsing the configuration object, that is, in the

ngx_events_block() method of parsing the events {} configuration block. of. This method essentially just creates an array of pointers and assigns it to the nginx core and the corresponding location of the conf_ctx of the ngx_cycle_t of the value object.

2. ngx_event_core_module

Before introducing the

ngx_event_core_module module, we first need to explain the interface definition of the event module:

typedef struct {
    // 事件模块的名称
    ngx_str_t *name;
    // 在解析配置项前，这个回调方法用于创建存储配置项参数的结构体
    void *(*create_conf)(ngx_cycle_t *cycle);
    // 在解析配置项完成后，init_conf()方法会被调用，用以综合处理当前事件模块感兴趣的全部配置项
    char *(*init_conf)(ngx_cycle_t *cycle, void *conf);
    // 对于事件驱动机制，每个事件模块需要实现的10个抽象方法
    ngx_event_actions_t actions;
} ngx_event_module_t;
typedef struct {
    // 添加事件方法，它负责把一个感兴趣的事件添加到操作系统提供的事件驱动机制（epoll、kqueue等）中，
    // 这样，在事件发生后，将可以在调用下面的process_events时获取这个事件
    ngx_int_t (*add)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags);
    // 删除事件方法，它把一个已经存在于事件驱动机制中的事件移除，这样以后即使这个事件发生，
    // 调用process_events()方法时也无法再获取这个事件
    ngx_int_t (*del)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags);
    // 启用一个事件，目前事件框架不会调用这个方法，大部分事件驱动模块对于该方法的实现都是
    // 与上面的add()方法完全一致的
    ngx_int_t (*enable)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags);
    // 禁用一个事件，目前事件框架不会调用这个方法，大部分事件驱动模块对于该方法的实现都是
    // 与上面的del()方法完全一致的
    ngx_int_t (*disable)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags);
    // 向事件驱动机制中添加一个新的连接，这意味着连接上的读写事件都添加到事件驱动机制中了
    ngx_int_t (*add_conn)(ngx_connection_t *c);
    // 从事件驱动机制中移除一个连接的读写事件
    ngx_int_t (*del_conn)(ngx_connection_t *c, ngx_uint_t flags);
    ngx_int_t (*notify)(ngx_event_handler_pt handler);
    // 在正常的工作循环中，将通过调用process_events()方法来处理事件。
    // 这个方法仅在ngx_process_events_and_timers()方法中调用，它是处理、分发事件的核心
    ngx_int_t (*process_events)(ngx_cycle_t *cycle, ngx_msec_t timer, ngx_uint_t flags);
    // 初始化事件驱动模块的方法
    ngx_int_t (*init)(ngx_cycle_t *cycle, ngx_msec_t timer);
    // 退出事件驱动模块前调用的方法
    void (*done)(ngx_cycle_t *cycle);
} ngx_event_actions_t;

The event module of nginx mainly has two configuration structures:

ngx_event_module_t and ngx_event_actions_t. As can be seen from the above definition, the ngx_event_module_t structure refers to ngx_event_actions_t.

ngx_event_module_t is mainly used to create and initialize the configuration structure required by the current module, while ngx_event_actions_t mainly defines the way the current event module handles each event. This interface is a typical implementation interface. They are various event models defined by nginx, such as epoll's ngx_epoll_module_ctx.actions and kqueue's ngx_kqueue_module_ctx.actions. It can be seen from here that the definition of the event module abstracts the relevant processing methods of each event-processing model.

For the event module, there is a module used to store the basic configuration related to events, namely

ngx_event_core_module. Although the ngx_event_module_t interface is implemented, its No specific event processing is performed. The following is the definition of the ngx_event_core_module module:

ngx_module_t ngx_event_core_module = {
    NGX_MODULE_V1,
    &ngx_event_core_module_ctx,            /* module context */
    ngx_event_core_commands,               /* module directives */
    NGX_EVENT_MODULE,                      /* module type */
    NULL,                                  /* init master */
    // 该方法主要是在master进程启动的过程中调用的，用于初始化时间模块
    ngx_event_module_init,                 /* init module */
    // 该方法是在各个worker进程启动之后调用的
    ngx_event_process_init,                /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};
static ngx_event_module_t ngx_event_core_module_ctx = {
    &event_core_name,
    ngx_event_core_create_conf,            /* create configuration */
    ngx_event_core_init_conf,              /* init configuration */
    // ngx_event_core_module_ctx并不直接负责TCP网络事件的驱动，
    // 因而这里的ngx_event_actions_t中的方法都为NULL
    {NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
};
static ngx_command_t ngx_event_core_commands[] = {
    // 连接池的大小，也即每个worker进程中支持的TCP最大连接数，它与connections配置项的意义是重复的
    {ngx_string("worker_connections"),
     NGX_EVENT_CONF | NGX_CONF_TAKE1,
     ngx_event_connections,
     0,
     0,
     NULL},
     // 确定选择哪一个事件模块作为事件驱动机制
    {ngx_string("use"),
     NGX_EVENT_CONF | NGX_CONF_TAKE1,
     ngx_event_use,
     0,
     0,
     NULL},
     // 对应于ngx_event_s中的available属性，对于epoll事件驱动模式来说，意味着在接收到一个新连接事件时，
     // 调用accept以尽可能多地接收连接
    {ngx_string("multi_accept"),
     NGX_EVENT_CONF | NGX_CONF_FLAG,
     ngx_conf_set_flag_slot,
     0,
     offsetof(ngx_event_conf_t, multi_accept),
     NULL},
     // 确定是否使用accept_mutex负载均衡锁，默认为开启
    {ngx_string("accept_mutex"),
     NGX_EVENT_CONF | NGX_CONF_FLAG,
     ngx_conf_set_flag_slot,
     0,
     offsetof(ngx_event_conf_t, accept_mutex),
     NULL},
     // 启用accept_mutex负载均衡锁后，延迟accept_mutex_delay毫秒后再试图处理新连接事件
    {ngx_string("accept_mutex_delay"),
     NGX_EVENT_CONF | NGX_CONF_TAKE1,
     ngx_conf_set_msec_slot,
     0,
     offsetof(ngx_event_conf_t, accept_mutex_delay),
     NULL},
     // 需要对来自指定IP的TCP连接打印debug级别的调试日志
    {ngx_string("debug_connection"),
     NGX_EVENT_CONF | NGX_CONF_TAKE1,
     ngx_event_debug_connection,
     0,
     0,
     NULL},
    ngx_null_command
};

在事件模块的定义中，module context指向的是一个ngx_event_module_t结构体，这里的ngx_event_core_module的module context指向的就是第二个结构体定义的ngx_event_core_module_ctx，而ngx_event_core_module_ctx中则定义了当前核心模块创建配置对象和初始化配置对象的方法，可以看到，其actions属性中的值全部为NULL，这是因为该模块并不负责处理具体的事件处理方案，而是负责核心结构体的创建和初始化，nginx也会保证这个模块在所有的事件模块中最先被调用，其余各个事件模块也可以引用该模块所存储的基础配置数据。

在ngx_event_core_module中第三个属性ngx_event_core_commands指向的是上面的第三个结构体，这个结构体中定义了当前事件模块所能使用的各个配置项的基本配置以及解析这些配置项的方法。

这里我们需要着重强调ngx_event_core_module中的第六个和第七个属性，这两个属性指向的是都是某个方法，第六个属性init module的主要是在nginx启动过程中解析完nginx.conf配置文件之后执行，其作用是对当前模块进行初始化的工作，而第七个属性init process主要是在nginx启动worker进程之后worker进程开始执行主循环之前调用的，其作用是进行worker进程执行前的初始化工作。

3. 模块方法的执行流程

通过上面的介绍我们大致了解了定义事件模块的两个核心模块的主要方法及其作用，这里则主要是对这些方法的执行流程进行讲解，如下是其流程示意图：

 对于上面的，这里需要对其各个步骤的功能进行说明：

1.解析nginx.conf文件，当遇到events配置项时，就使用ngx_evetns_block()方法对其进行解析；

2.创建用于存储各个事件模块存储配置项的结构体的数组；

3.采用递归的方式解析events配置块中的子配置项；

4.依次检查事件核心模块的配置项，如果其没有赋值，则对其赋一个默认值；

5.检查是否创建了存储事件模块配置项的数组，该检查的主要目的是判断核心模块是否成功初始化了；

6.主要是通过解析得到的配置项，设置诸如时间定时器的执行频率、可打开的文件句柄限制和初始化记录统计数据的属性；

7.在worker进程中调用，用于初始化worker进程运行所需要的环境，比如初始化事件队列、初始化事件模型、添加时间更新的定时任务等；

The above is the detailed content of Detailed explanation of nginx event module structure. For more information, please follow other related articles on the PHP Chinese website!