Understanding Swoole Server: Fundamentals, Modes, and Request Processing Flow

1. Fundamentals

1.1 Swoole

Swoole is a production‑ready asynchronous network engine for PHP, enabling developers to build high‑performance server services. This article gives a brief overview of Swoole's server component, with detailed implementation to be covered in later posts.

1.2 Network Programming

Network communication involves launching one or more processes that listen on ports and exchange information with clients using protocols such as HTTP, DNS, or custom protocols. Swoole's server is built on TCP and UDP, focusing on TCP‑based programming.

The TCP programming model includes four key events:

Connection establishment : client connect and server accept .

Message arrival : server receives data; handling may be blocking or non‑blocking, with considerations for packet fragmentation and application‑level buffering.

Message sent successfully : data is placed into the kernel socket send buffer; for non‑blocking I/O, the actual bytes written must be verified.

Connection termination : client disconnect ( read returns 0) or server close ( close , shutdown ).

TCP connection establishment and termination processes are illustrated with the following diagrams:

ACK and SYN are flag bits; seq and ack are sequence and acknowledgment numbers.

FIN and ACK indicate connection teardown.

1.3 Inter‑Process Communication

Common IPC mechanisms include unnamed pipes, named pipes (FIFO), signals, semaphores, sockets, and shared memory. Swoole uses Unix domain sockets for communication between its internal processes.

1.4 socketpair

socketpair creates a bidirectional socket pair, unlike a unidirectional pipe. After a successful call, sv[0] and sv[1] hold file descriptors that can be used for reading and writing in both directions, and are inherited by forked child processes for parent‑child communication.

1.5 Daemon (Background Process)

A daemon detaches from the terminal and runs in the background, typically performing periodic tasks. It involves concepts of process groups, sessions, and the setsid system call to become the session leader and lose any controlling terminal.

1.6 Swoole TCP Server Example

The example code runs in CLI mode, is parsed into opcodes by the Zend VM, and starts the Swoole server with $serv->start() . Event callbacks are executed in worker processes; further details are covered later.

2. Swoole Server

2.1 Base Mode

Base mode uses a multi‑process model similar to Nginx: a master process manages worker processes, each with a single thread handling listening, accepting, processing, and closing connections. The SO_REUSEPORT socket option (available from Linux 3.9) mitigates the thundering‑herd problem.

When the worker count is set to 1, no worker processes are forked and the master handles requests directly, which is useful for debugging.

2.2 Process Mode

Process mode employs multiple processes and threads: a master process, a manager process, worker processes, and optional task_worker processes. The master creates a reactor thread that accepts connections and forwards data to workers via Unix domain sockets. The manager oversees worker lifecycles, and task workers handle time‑consuming tasks.

Startup flow: the entry point swServer_start forks the manager, which then forks workers and task workers. Reactor threads and worker threads each run their own event loops.

3. Request Handling Flow (Process Mode)

3.1 Communication Between Reactor Thread and Worker Process

The master uses SOCK_DGRAM sockets to exchange messages with workers, allowing the reactor to forward client requests without dealing with TCP stream fragmentation.

Each reactor thread is assigned a subset of workers (default: worker_process_id % reactor_num ). Workers receive packets containing a header with routing information.

3.2 Request Processing

The master’s main thread listens on a port ( listen ) and accepts connections ( accept ), creating a file descriptor (fd). The fd is assigned to a reactor thread (typically fd % reactor_number ) and added to the reactor’s epoll set via epoll_ctl . Initially the fd is monitored for write events, which immediately trigger initialization.

After the first write event, the reactor switches to read monitoring to receive client data. Once a complete request is read, it is forwarded to a worker (usually fd % worker_number ) with a header indicating the originating reactor.

Workers process the request and send the result back to the master, again encapsulated in a packet with a header. The master then routes the response to the appropriate reactor thread, which may send data back to the client or modify the connection state (e.g., close ) using epoll_ctl .

4. GDB Debugging

4.1 Process Mode Startup

4.2 Base Mode Startup

5. Summary and Thoughts

The article introduced Swoole server’s two modes—base and process—explaining their network programming models, inter‑process communication, and request handling flow. It also discussed why PHP prefers a manager‑worker architecture over multithreading, the concurrency characteristics of reactors and workers, and the need for user‑level packet framing when using raw TCP.

6. References

UNIX Network Programming

Advanced UNIX Programming

PHP7 Internals and Source Code Analysis

Swoole Official Wiki

Blog Post 1

Blog Post 2