ngx_epoll_module是nginx眾多事件模組的其中一個，它利用linux的epoll模型實現nginx事件框架所定義的事件模組介面。執行在linux系統上的nginx預設使用該模組作為事件框架的底層實現。

ngx_epoll_module主要是實現了ngx_event.h中規定的事件模組的介面，即實現了ngx_event_module_t中定義的那組回撥函式，如下程式碼片段所示：

static ngx_event_module_t  ngx_epoll_module_ctx = {
    &epoll_name, /* epoll */
    ngx_epoll_create_conf,               /* create configuration */
    ngx_epoll_init_conf,                 /* init configuration */

    {
        ngx_epoll_add_event,             /* add an event */
        ngx_epoll_del_event,             /* delete an event */
        ngx_epoll_add_event,             /* enable an event */
        ngx_epoll_del_event,             /* disable an event */
        ngx_epoll_add_connection,        /* add an connection */
        ngx_epoll_del_connection,        /* delete an connection */
#if (NGX_HAVE_EVENTFD)
        ngx_epoll_notify,                /* trigger a notify */
#else
        NULL,                            /* trigger a notify */
#endif
        ngx_epoll_process_events,        /* process the events */
        ngx_epoll_init,                  /* init the events */
        ngx_epoll_done,                  /* done the events */
    }
};
 

模組一共提供了兩個指令，epoll_events和worker_aio_requests，分別對應於一次epoll_wait允許處理的最大事件數和非同步請求數，它們的預設值分別是512和32。

ngx_epoll_create_conf和ngx_epoll_init_conf用於建立和初始化模組配置，這裡略過，重點關注ngx_epoll_init，ngx_epoll_add_event，ngx_epoll_del_event，ngx_epoll_process_events以及ngx_epoll_add_connection和ngx_epoll_del_connection。

ngx_epoll_init

在所有介面中，ngx_epoll_init是最先被呼叫的介面，因為它的工作是為模組的執行建立和配置環境。ngx_epoll_init介面在worker程序啟動過程中，開始提供服務前被呼叫。它只會被呼叫一次

static ngx_int_t 
ngx_epoll_init(ngx_cycle_t *cycle, ngx_msec_t timer)
{
    ngx_epoll_conf_t  *epcf;

    epcf = ngx_event_get_conf(cycle->conf_ctx, ngx_epoll_module);

    /* 建立epoll檔案 */
    if (ep == -1) {
        ep = epoll_create(cycle->connection_n / 2);

        if (ep == -1) {
            ngx_log_error(NGX_LOG_EMERG, cycle->log, ngx_errno,
                          "epoll_create() failed");
            return NGX_ERROR;
        }

/* 事件通知環境初始化 */
#if (NGX_HAVE_EVENTFD)
        if (ngx_epoll_notify_init(cycle->log) != NGX_OK) {
            ngx_epoll_module_ctx.actions.notify = NULL;
        }
#endif

/* 檔案非同步IO初始化 */
#if (NGX_HAVE_FILE_AIO)
        ngx_epoll_aio_init(cycle, epcf);
#endif

/* 測試是否支援EPOLLRDHUP */
#if (NGX_HAVE_EPOLLRDHUP)
        ngx_epoll_test_rdhup(cycle);
#endif
    }

    /* 建立epoll事件陣列，陣列大小與配置的events一致，預設是512 */
    if (nevents < epcf->events) {
        if (event_list) {
            ngx_free(event_list);
        }

        event_list = ngx_alloc(sizeof(struct epoll_event) * epcf->events,
                               cycle->log);
        if (event_list == NULL) {
            return NGX_ERROR;
        }
    }

    nevents = epcf->events;
    
    /* 設定ngx_io為ngx_os_io。
     * 其它模組進行網路io的時候呼叫的是
     * ngx_io中的介面，因此在worker程序開始工作前
     * 就必須先設定好，實際上其它事件模組也是這麼做的
     * /
    ngx_io = ngx_os_io;
    
    /* 這一步很關鍵。nginx事件框架和外部介面呼叫的是ngx_event_actions
     * 中定義的介面，雖然在ngx_event_core_module的
     * ngx_event_core_init_conf函式中已經選定了要使用的事件模組，
     * 但是並沒有將ngx_event_actions與具體的事件模組進行對映，不能
     * 正常工作，所以這裡將ngx_event_actions對映到epoll模組
     * 的介面上。通過這樣的方式，呼叫ngx_event_actions的介面實際上就是
     * 呼叫epoll模組的介面。
     * /
    ngx_event_actions = ngx_epoll_module_ctx.actions;

#if (NGX_HAVE_CLEAR_EVENT)
    /* epoll邊緣觸發 */
    ngx_event_flags = NGX_USE_CLEAR_EVENT
#else
    /* epoll水平觸發 */
    ngx_event_flags = NGX_USE_LEVEL_EVENT
#endif
    /* 這兩個標誌在別處會用到，所以需要設定 */
                      |NGX_USE_GREEDY_EVENT
                      |NGX_USE_EPOLL_EVENT;

    return NGX_OK;
}
 

ngx_epoll_add_event

ngx_epoll_add_event用於向事件框架中新增事件，核心是使用epoll_ctl實現

static ngx_int_t
ngx_epoll_add_event(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags)
{
    int                  op;
    uint32_t             events, prev;
    ngx_event_t         *e;
    ngx_connection_t    *c;
    struct epoll_event   ee;

    /* 除了個別場景，大部分情況下事件的data都指向所對應的連線 */
    c = ev->data;

    events = (uint32_t) event;
    
    if (event == NGX_READ_EVENT) {
        e = c->write;
        prev = EPOLLOUT;
#if (NGX_READ_EVENT != EPOLLIN|EPOLLRDHUP)
        events = EPOLLIN|EPOLLRDHUP;
#endif

    } else {
        e = c->read;
        prev = EPOLLIN|EPOLLRDHUP;
#if (NGX_WRITE_EVENT != EPOLLOUT)
        events = EPOLLOUT;
#endif
    }

    if (e->active) {
        op = EPOLL_CTL_MOD;
        events |= prev;

    } else {
        op = EPOLL_CTL_ADD;
    }

#if (NGX_HAVE_EPOLLEXCLUSIVE && NGX_HAVE_EPOLLRDHUP)
    if (flags & NGX_EXCLUSIVE_EVENT) {
        events &= ~EPOLLRDHUP;
    }
#endif

    ee.events = events | (uint32_t) flags;
    ee.data.ptr = (void *) ((uintptr_t) c | ev->instance);

    ngx_log_debug3(NGX_LOG_DEBUG_EVENT, ev->log, 0,
                   "epoll add event: fd:%d op:%d ev:%08XD",
                   c->fd, op, ee.events);

    if (epoll_ctl(ep, op, c->fd, &ee) == -1) {
        ngx_log_error(NGX_LOG_ALERT, ev->log, ngx_errno,
                      "epoll_ctl(%d, %d) failed", op, c->fd);
        return NGX_ERROR;
    }

    ev->active = 1;
#if 0
    ev->oneshot = (flags & NGX_ONESHOT_EVENT) ? 1 : 0;
#endif

    return NGX_OK;
}

ngx_epoll_del_event

ngx_epoll_del_event用於刪除事件，同樣也是使用epoll_ctl實現

ngx_epoll_process_events

該函式是處理事件的核心所在，在使用epoll作為IO多路複用模型的情況下，ngx_process_events_and_timers函式中呼叫的ngx_process_events實際上就是這個函式。

static ngx_int_t
ngx_epoll_process_events(ngx_cycle_t *cycle, ngx_msec_t timer, ngx_uint_t flags)
{
    int                events;
    uint32_t           revents;
    ngx_int_t          instance, i;
    ngx_uint_t         level;
    ngx_err_t          err;
    ngx_event_t       *rev, *wev;
    ngx_queue_t       *queue;
    ngx_connection_t  *c;

    /* NGX_TIMER_INFINITE == INFTIM */

    ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
                   "epoll timer: %M", timer);

    events = epoll_wait(ep, event_list, (int) nevents, timer);

    err = (events == -1) ? ngx_errno : 0;

    /* 如果設定了NGX_UPDATE_TIME或者設定了時間精度並且觸發了事件精度事件，
     * 就更新快取時間 */
    if (flags & NGX_UPDATE_TIME || ngx_event_timer_alarm) {
        ngx_time_update();
    }

    /* epoll_wait呼叫失敗，如果系統錯誤碼是EINTR，說明是被優先順序更高的系統調
     * 用打斷（例如接收到訊號），這種情況下不視為錯誤，其它情況下視為
     *epoll_wait失敗 */
    if (err) {
        if (err == NGX_EINTR) {

            if (ngx_event_timer_alarm) {
                ngx_event_timer_alarm = 0;
                return NGX_OK;
            }

            level = NGX_LOG_INFO;

        } else {
            level = NGX_LOG_ALERT;
        }

        ngx_log_error(level, cycle->log, err, "epoll_wait() failed");
        return NGX_ERROR;
    }

    /* events為0，說明沒有事件發生。如果timer是-1，epoll_wait在沒有
     * 事件發生時不會返回，這說明在某個地方出現了問題 */
    if (events == 0) {
        if (timer != NGX_TIMER_INFINITE) {
            return NGX_OK;
        }

        ngx_log_error(NGX_LOG_ALERT, cycle->log, 0,
                      "epoll_wait() returned no events without timeout");
        return NGX_ERROR;
    }

    for (i = 0; i < events; i++) {
        c = event_list[i].data.ptr;

        instance = (uintptr_t) c & 1;
        c = (ngx_connection_t *) ((uintptr_t) c & (uintptr_t) ~1);

        rev = c->read;

        /* 如果fd是-1，或者instance與連線的instance標誌不一致，
         * 說明在這個時刻，該讀事件已經是過期事件，不應該再處理。
        if (c->fd == -1 || rev->instance != instance) {

            /*
             * the stale event from a file descriptor
             * that was just closed in this iteration
             */

            ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
                           "epoll: stale event %p", c);
            continue;
        }

        revents = event_list[i].events;

        ngx_log_debug3(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
                       "epoll: fd:%d ev:%04XD d:%p",
                       c->fd, revents, event_list[i].data.ptr);

        if (revents & (EPOLLERR|EPOLLHUP)) {
            ngx_log_debug2(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
                           "epoll_wait() error on fd:%d ev:%04XD",
                           c->fd, revents);

            /*
             * if the error events were returned, add EPOLLIN and EPOLLOUT
             * to handle the events at least in one active handler
             */

            revents |= EPOLLIN|EPOLLOUT;
        }

#if 0
        if (revents & ~(EPOLLIN|EPOLLOUT|EPOLLERR|EPOLLHUP)) {
            ngx_log_error(NGX_LOG_ALERT, cycle->log, 0,
                          "strange epoll_wait() events fd:%d ev:%04XD",
                          c->fd, revents);
        }
#endif

        if ((revents & EPOLLIN) && rev->active) {

#if (NGX_HAVE_EPOLLRDHUP)
            if (revents & EPOLLRDHUP) {
                rev->pending_eof = 1;
            }

            rev->available = 1;
#endif

            rev->ready = 1;
            
            /* 如果設定了NGX_POST_EVENTS，說明該事件要延後處理。
             * 如果是accept事件，就把事件放到accept_post佇列中，否則
             * 放到普通的post佇列中
            if (flags & NGX_POST_EVENTS) {
                queue = rev->accept ? &ngx_posted_accept_events
                                    : &ngx_posted_events;

                ngx_post_event(rev, queue);

            } else {
                /* 不需要延後處理，立即呼叫handler */
                rev->handler(rev);
            }
        }

        wev = c->write;

        if ((revents & EPOLLOUT) && wev->active) {
            
        /* 如果fd是-1，或者instance與連線的instance標誌不一致，
         * 說明在這個時刻，該寫事件已經是過期事件，不應該再處理。
            if (c->fd == -1 || wev->instance != instance) {

                /*
                 * the stale event from a file descriptor
                 * that was just closed in this iteration
                 */

                ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
                               "epoll: stale event %p", c);
                continue;
            }

            wev->ready = 1;
#if (NGX_THREADS)
            wev->complete = 1;
#endif
            /* 如果設定了NGX_POST_EVENTS，說明該事件要延後處理，
             * 將其放到post事件佇列中 */
            if (flags & NGX_POST_EVENTS) {
                ngx_post_event(wev, &ngx_posted_events);

            } else {
                /* 不需要延後，立即呼叫handler處理 */
                wev->handler(wev);
            }
        }
    }

    return NGX_OK;
}

ngx_epoll_add_connection

新增連線，相當於把連線相關的事件及其觸發方式（讀寫，對端關閉，邊緣觸發）一次性註冊，並且設定讀寫事件為啟用狀態，程式碼如下

static ngx_int_t
ngx_epoll_add_connection(ngx_connection_t *c)
{
    struct epoll_event  ee;

    ee.events = EPOLLIN|EPOLLOUT|EPOLLET|EPOLLRDHUP;
    ee.data.ptr = (void *) ((uintptr_t) c | c->read->instance);

    ngx_log_debug2(NGX_LOG_DEBUG_EVENT, c->log, 0,
                   "epoll add connection: fd:%d ev:%08XD", c->fd, ee.events);

    if (epoll_ctl(ep, EPOLL_CTL_ADD, c->fd, &ee) == -1) {
        ngx_log_error(NGX_LOG_ALERT, c->log, ngx_errno,
                      "epoll_ctl(EPOLL_CTL_ADD, %d) failed", c->fd);
        return NGX_ERROR;
    }

    c->read->active = 1;
    c->write->active = 1;

    return NGX_OK;
}

ngx_epoll_del_connection

刪除連線。把連線相關的事件從框架中刪除，並且把連線的讀寫事件設定為非啟用

static ngx_int_t
ngx_epoll_del_connection(ngx_connection_t *c, ngx_uint_t flags)
{
    int                 op;
    struct epoll_event  ee;

    /*
     * when the file descriptor is closed the epoll automatically deletes
     * it from its queue so we do not need to delete explicitly the event
     * before the closing the file descriptor
     */

    if (flags & NGX_CLOSE_EVENT) {
        c->read->active = 0;
        c->write->active = 0;
        return NGX_OK;
    }

    ngx_log_debug1(NGX_LOG_DEBUG_EVENT, c->log, 0,
                   "epoll del connection: fd:%d", c->fd);

    op = EPOLL_CTL_DEL;
    ee.events = 0;
    ee.data.ptr = NULL;

    if (epoll_ctl(ep, op, c->fd, &ee) == -1) {
        ngx_log_error(NGX_LOG_ALERT, c->log, ngx_errno,
                      "epoll_ctl(%d, %d) failed", op, c->fd);
        return NGX_ERROR;
    }

    c->read->active = 0;
    c->write->active = 0;

    return NGX_OK;
}