Inside Nginx: How It Starts, Handles Requests, and Key Callbacks Explained

Early on I wanted to read Nginx source code, and after a busy period I finally did, finding the overall structure understandable and deciding to learn Nginx+Lua development.

This note records my observations, focusing on four main points:

Nginx startup process

Important callback function settings

Nginx HTTP request handling

Summary

1. Nginx Startup Process

Nginx is large, so a macro‑level analysis is more feasible. To debug with GDB you must compile with the -g option. Edit nginx/auto/cc/conf and change ngx_compile_opt="-c" to ngx_compile_opt="-c -g", then run ./configure && make to produce the executable in the objs directory.

Run the binary; it loads the default configuration and daemonizes. Attach GDB to the master and worker processes using their PIDs (e.g., pidof nginx then gdb -p <pid>).

The master process starts from main(), performs initialization, creates a PID file, and calls ngx_master_process_cycle(), which forks worker processes and then blocks on signals.

Signal handling is implemented via pipes: each worker has a read/write descriptor pair; the master writes a flag to the write end, workers detect the flag via epoll/kqueue and act accordingly.

Worker processes inherit the master’s stack. The startup chain is: ngx_start_worker_processes() → ngx_spawn_process() (sets up pipes and forks)

Child runs ngx_worker_process_cycle(), which calls ngx_worker_process_init() to set priorities, file descriptor limits, signal masks, and module initialization.

Then it enters an infinite loop calling ngx_process_events_and_timers(), which acquires the accept lock, registers the listening socket, and dispatches events via ngx_process_events() (e.g., ngx_epoll_process_events()).

To avoid the thundering‑herd problem, workers compete for the accept lock; the winner handles the client connection while others only process already‑accepted events.

2. Important Callback Function Settings

After the master and workers are running, client requests arrive. The listening socket’s read callback is set during event module initialization in ngx_event_process_init(), where ngx_event_accept is assigned to each listenfd.

Functions ngx_add_conn and ngx_add_event are pointers stored in the ngx_event_actions structure, which varies by platform (epoll on Linux, kqueue on macOS, poll otherwise). The appropriate platform‑specific functions (e.g., ngx_epoll_add_connection, ngx_kqueue_add_event) are invoked.

When a client connects, the listenfd callback calls accept(), obtains a ngx_connection_t from the pool, registers it with the event system, and finally invokes the handler stored in ls->handler. This handler is set by the HTTP module during configuration parsing (the http directive) and points to ngx_http_init_connection(), the entry point for HTTP request processing.

3. Nginx HTTP Request Processing

The HTTP module processes a request in three high‑level steps:

Read and parse the request line

Read and parse request headers

Enter the multi‑phase handler chain

After the line and headers are parsed, the request is stored in a ngx_http_request_t structure. Nginx then runs through 11 processing phases, each with its own handler (e.g., URI rewrite, access control, content generation, logging). This design is similar to middleware pipelines in frameworks like Python’s WSGI or Go’s net/http.

To illustrate module registration, I created a minimal third‑party module:

Create a thm/foo directory with ngx_http_foo_module.c Add a simple config file

Register a handler in the NGX_HTTP_CONTENT_PHASE Recompile Nginx and load the module

Using GDB, I set a breakpoint at the content phase and observed the call chain:

Client connection triggers ngx_epoll_process_events → ngx_event_accept Connection is wrapped in ngx_connection_t and passed to

ngx_http_init_connection

ngx_http_init_connection

calls ngx_http_init_request, which invokes ngx_http_process_request_line and ngx_http_process_request_header The request is finally handled by ngx_http_handler, which runs ngx_http_core_run_phases where the registered ngx_http_foo_handler executes.

4. Summary

This note offers a macro‑level view of Nginx’s execution flow, from process startup and inter‑process communication to event‑driven request handling and the multi‑phase architecture that enables third‑party module integration. Further study of the phase handlers will deepen understanding of custom module development.