Understanding Swoole Heartbeat: Keep Your PHP Server Connections Alive

Swoole is a high‑performance asynchronous network engine for PHP, written in C, providing async TCP/UDP servers, async MySQL/Redis, connection pools, async tasks, timers, and more.

The article explains Swoole’s heartbeat feature, which determines whether a connection is still alive.

What is a heartbeat?

A heartbeat is a standard to judge if something is alive; in Swoole it checks if a connection is normal or has been closed.

TCP basics

A network connection is identified by a five‑tuple and established via a three‑way handshake, while termination uses a four‑way handshake. When a connection is closed, the server eventually releases the file descriptor (fd) and triggers the onClose callback.

What is an fd?

An fd (file descriptor) is the system‑level identifier for a network connection, acting as an index that the kernel uses to perform operations such as sending data or closing the connection.

Why need a heartbeat?

If a client abruptly disconnects (e.g., cable unplugged), the server may not detect the failure, causing the fd to remain occupied and eventually exhausting available connections. A heartbeat mechanism reclaims such dead connections.

Heartbeat mechanism

Two common approaches:

Client periodically sends a heartbeat packet; the server checks the last received time and closes connections that exceed a timeout.

Server periodically queries clients for a response; unresponsive clients are terminated.

Which approach does Swoole use?

Swoole adopts the first approach. It runs a dedicated heartbeat thread in the master process that polls all connections without blocking business logic. Each connection has a time_t last_time field storing the timestamp of the last received packet; the thread compares it with the current time to decide liveness.

Swoole provides two configuration options: heartbeat_check_interval: interval for the server to scan the connection list. heartbeat_idle_time: maximum idle time; if the gap between the last heartbeat and the current time exceeds this value, the connection is considered dead.

Configuration recommendation

Set heartbeat_idle_time to slightly more than twice heartbeat_check_interval to allow for one lost packet and network latency. Adjust based on actual business tolerance.

Additional notes

The operating system also offers a coarse‑grained heartbeat, but Swoole’s application‑level mechanism is more flexible. Swoole also supports a ping feature that distinguishes heartbeat packets without delivering them to the onReceive callback. Heartbeat concepts are common to most TCP services.