Skip to content

Process model ​

Rapira runs one master process and a worker pool for each enabled protocol. The master owns the listen sockets, initialized PHP engine, and pidfile. The master then creates worker processes. Each worker inherits PHP and accepts connections from its pool's shared socket. Rapira does not pass a request between processes.

HTTP and gRPC have separate listeners, entrypoints, and pools. [http.pool] and [grpc.pool] configure them independently. The gRPC pool uses Dispatcher mode and handles one active call per worker.

When the configuration has an [observability] table, the master also starts one process for metrics and health checks. This process runs no PHP code. On Linux, its process name is rapira-obs, and PHP workers have the name rapira-worker. The master supervises and stops this process together with the PHP workers. A reload does not change it, because it has no app to restart. See Metrics and health checks for more information.

This process model is the same in Classic, Worker, and Dispatcher modes. http.pool.mode controls request processing inside a worker. This setting does not change pool creation, supervision, or reloads. See Execution modes for more information.

Master and workers ​

Initialization uses this order:

  1. Bind the listen socket or sockets. A port conflict stops initialization before PHP starts.
  2. Start PHP once. The master runs MINIT in its single thread. OPcache creates its shared memory at this point, and every worker inherits it. When one worker compiles a file, the other workers use the cached result.
  3. Fork the workers. Each child inherits the bound socket and the initialized engine.

The diagram shows one pool. Each worker runs one NTS PHP interpreter and an asynchronous HTTP or gRPC server. The server uses hyper on a private tokio runtime with two threads. Each worker calls accept() on its inherited socket. The operating system assigns each new connection to one worker.

The master does not serve requests. Its single thread waits for signals, worker exits, and timers.

The master keeps the PHP module for its complete lifetime. Only the master shuts down the module. A worker exits but does not shut down this shared engine state.

Supervision ​

The master runs maintenance once each second. It also processes each worker exit when it occurs.

  • Worker replacement. After a normal exit, the master replaces the worker immediately. After a crash or an unhealthy exit, the replacement delay starts at 100 ms. The delay doubles after each consecutive failure and stops at 25.6 seconds. A worker that runs for at least 10 seconds resets the delay.
  • Boot failures. In Worker and Dispatcher modes, a boot fails when the entry script ends before it receives a request. The worker then waits up to 5 seconds and runs the entry script again. It answers a request that arrives during the wait with HTTP 503 or gRPC UNAVAILABLE. After five consecutive boot failures, the worker exits as unhealthy.
  • Master stop on boot failure. The master stops with exit code 70 when an unhealthy worker exits. This rule applies only when the pool has no successful request and no idle or active worker. In all other cases, the master replaces the worker after the replacement delay. A worker crash never stops the master.
  • Request limits. In Worker and Dispatcher modes, http.pool.max_requests limits the requests of one app instance. After a random number of requests between max_requests + 1 and approximately 1.5 × max_requests, the worker restarts its app. The worker process, its connections, and its queue stay. The next request waits for the app to start. The random range prevents simultaneous restarts. Classic mode ignores this setting, because each request runs in a new PHP request.
  • Request timeout. With http.pool.request_terminate_timeout_secs, the master sends SIGTERM to a worker when its current request exceeds the limit. If the worker is still active at the next maintenance run, the master sends SIGKILL. The master then replaces the worker immediately. The master does not apply this timeout during a stop.
  • Memory limit. Outside a stop, the master checks each worker's RSS once per second and sends SIGQUIT once above http.pool.max_memory_mb. The worker stops accepting new connections; existing connections can receive their next response within the drain timeout. Responses that exceed this timeout can be cut short. The master starts a replacement after the worker exits, which releases memory inside and outside PHP. RSS can stay high after an app restart because PHP keeps some freed memory for reuse.
  • Master monitoring. Each worker reads from a pipe that the master keeps open. If the master exits, each worker stops accepting new work, finishes its current requests, and exits.

Pool size ​

The settings below use [http.pool]. The same settings apply to [grpc.pool].

http.pool.processes sets the worker count. The master creates these workers during initialization and replaces each worker that exits. The default value is one worker for each CPU that the process can use. If a container has a CPU limit, the default follows that limit.

The total worker count of all pools must be 4096 or less. When observability is enabled, its process counts as one worker. A larger total stops Rapira with exit code 70.

PHP is synchronous, so each worker handles one request at a time. I/O-bound applications can require more workers than CPU cores. CPU-bound applications usually do not.

The worker count does not change while the server runs. To change the capacity with the load, change the number of Rapira instances, for example with a container orchestrator.

See configuration for the complete key reference.

Signals ​

Signals stop a running server, reload it, and make it report its state. All of them go to the master.

SignalWhat the master does
SIGTERM, SIGINTThe master lets current requests finish and then stops the workers. A second signal forces the workers to stop.
SIGQUITThe master does the same controlled stop. Another SIGQUIT has no effect.
SIGUSR2, SIGHUPThe master tells each worker to restart its app. No worker process is replaced.
SIGUSR1The master writes pool status to the log.

Set supervisor.pidfile to give scripts a stable location for the master process identifier:

bash
kill -USR2 $(cat /run/rapira.pid)   # Restart the app in each worker.
kill -USR1 $(cat /run/rapira.pid)   # Write pool status to the log.
kill -TERM $(cat /run/rapira.pid)   # Stop after current requests finish.

Send signals only to the master. Workers ignore SIGUSR1. SIGUSR2 makes a worker restart its app. SIGTERM and SIGHUP stop a worker immediately and cut its current requests. The request timeout uses SIGTERM. A direct worker signal bypasses master supervision.

Ctrl-C in a terminal sends SIGINT to the master and to all workers. Each worker then also gets SIGQUIT from the master. A second stop signal makes a worker exit immediately with code 131, so its current requests do not finish. To let current requests finish, send SIGTERM to the master only.

Stopping ​

After a stop signal, the master immediately sends SIGQUIT to each worker. The workers do not accept new connections and finish current requests. Each worker keeps the connections that it holds. It answers the next request on each connection with Connection: close, and then the connection closes. After supervisor.process_control_timeout_secs, the master sends SIGTERM to workers that remain. The default limit is 30 seconds. If workers remain, the master sends SIGKILL one second after SIGTERM.

The connection drain budget is the control timeout minus the smaller of five seconds or half the timeout. With the default settings, connections have 25 seconds to finish. Responses that exceed this budget can be cut short. A connection that stays idle for the complete budget closes when the budget ends.

A second SIGTERM or SIGINT skips the wait and forces the exit immediately. See Exit codes for the exit codes of the master.

A reload restarts the apps ​

SIGUSR2 or SIGHUP restarts the app in each worker of each pool. The worker ends the PHP request of the app and runs the entry script again in the same process. Before the script runs, the worker resolves the symbolic links in the entry script path and changes its working directory to the script directory. The listener, the connections, and the queued requests stay. The old app serves the requests that wait in the queue before the signal. Later requests go to the new app.

In Classic mode, each request runs the entry script in a new PHP request. Thus, a changed file takes effect without a reload, except with opcache.validate_timestamps = 0. A deployment that switches a symbolic link in the entry script path needs a reload in all modes, Classic mode included. Worker and Dispatcher modes keep the application in memory. Reload the pool after each deployment in these modes. See deployment for more information.

A reload empties OPcache, so the apps load the new code also when opcache.validate_timestamps = 0. The manual_restarts value of opcache_get_status() counts these reloads. After a reload, the first requests compile their PHP files again. Requests run without OPcache until the longest request that was active at the reload ends. In Classic mode, a request that starts after its worker received the reload runs the new code, and active requests end with the old code.

Each worker restarts its app on its own. In Worker and Dispatcher modes with OPcache, most workers start the app two times during a reload. Thus, the code before the worker loop runs two times. When all workers restart at the same time, each queue waits only for the app starts of its own worker. A client does not see the restart, except for this wait.

The master ignores a reload signal during a stop. It does not log the ignored signal.

A reload restarts the apps but not the processes. The workers keep the same initialized engine. Restart Rapira to apply changes to the binary or to files that the master reads, such as rapira.toml and php.ini. Also restart it after a change to a file that opcache.preload loads.

OPcache schedules a restart when app code calls opcache_reset() or when the cache is full. Rapira then reloads every pool and logs one warning record. No worker process stops, and no connection closes. Under Rapira, the default of opcache.force_restart_timeout is 0, and a value in php.ini replaces it. With a value above 0, OPcache can kill a worker whose request runs longer than this time during an OPcache restart, also during a reload. Keep the value 0.

Writing status to the log ​

SIGUSR1 makes the master write the status of each pool to the log. The first line of a pool shows the running and idle worker counts. Then one line for each worker slot shows the process identifier, the state, and three counters:

text
status: http pool: 4 running, 3 idle
  slot 0 pid 4242 state 2 handled 1500 errors 2 recycles 0
StateMeaning
1Starting. The application did not boot yet, or its last boot failed.
2Idle. The worker waits for work.
3Active. The worker processes a request.
4Draining. The worker finishes its work and exits.

A slot keeps its counters when the master replaces its worker. recycles counts restarts of the app inside a worker, for example after max_requests or a reload.

The status output uses info on the master target. The default log level is error. Set this target to info to show the output:

toml
[log.targets]
master = "info"

The same target contains spawn errors and request timeout warnings. See logging for more information.

Does Rapira use transparent huge pages?

No. On Linux, the master turns off transparent huge pages for its own process before PHP starts. Workers and the processes that PHP starts with proc_open() or exec() inherit this setting. Thus, USE_ZEND_ALLOC_HUGE_PAGES=1 and opcache.huge_code_pages get no transparent huge pages. These options can still use explicit huge pages that the host reserves with vm.nr_hugepages. No setting changes this behavior.

Can the master run as PID 1 in a container?

Yes. As PID 1, the master handles the stop signals and removes all exited child processes. You do not need a separate init process.