Swoole\Server->reload()

4.x is outdated, please check the latest version 22.x


Latest version: pecl install openswoole-22.1.2

Declaration

<?php Swoole\Server->reload(bool $onlyReloadTaskworker = false): bool

Parameters

onlyReloadTaskworker

Default is false, allows you to decide between restarting the whole server or just task worker threads

Return

success

If success, it returns a true otherwise it returns false.

Swoole Hot Code Reloading

Swoole loads all PHP files into memory and reuses the code for serving different requests. New changes to any code can't be seen immediately like with PHP-FPM because FPM uses a stateless shared nothing design, Swoole is constant, using a stateful design, the script is started from PHP CLI and runs in memory. You have to reload the changed files with the hot reload function on demand.

For example, inotify can be used in Linux to monitor the changed files, then trigger the reload function. But please make sure inotify is supported by your server OS. Or you can use fswatch.

The reload() function will safely restart all the worker processes gracefully and reload all PHP files without interrupting the running server.

Files included within onWorkerStart and onReceive can be reloaded without restarting the server, but you can't reload files included before the start of the Swoole\Server.

You can't reload the runtime setting of the Swoole Server, you must stop and start the server again.

You can reload files included in Task Workers only with $onlyReloadTaskworker = true.

Safe Restarts

The whole point of hot code reloading is to aid in development, making it easier to test new code changes locally or over a network but the reload functionality can be used in production. Swoole will not accept multiple reload events if one is currently in place, if new reload signals get sent, they will be discarded until the current active reload has completed. - A complete reload means Swoole has to wait for worker threads to finish handling a request and the same goes for task workers, everything is handled in a graceful manner.

PHP User-land Reloading

Trigger a worker or task worker reload by using the reload function: $server->reload(). You can work out if you need to restart or not using PHP.

Hot Code Linux Signal Trigger

You can also trigger the hot code reloading function with Linux signals:

Restart both workers and task workers:

kill -USR1 MASTER_PID

Only restart the task processes by signal:

kill -USR2 MASTER_PID

Checking loaded files

You can see which files are loaded before the worker started:

<?php
$server->on('WorkerStart', function($serv, $workerId)
{
    // Files which won't be reloaded
    var_dump(get_included_files());

    // Include files from here so they can be reloaded...
});

The files which will be dumped from the above example cannot be reloaded because they have been included before the worker starts, files need to be included during a worker start event

APC/OpCache and hot reloading

  • stat in APC/OpCache has to be enabled for code reloading
  • Refresh OpCache with apc_clear_cache() or opcache_reset() if necessary

Server Reload Events

You can handle any pre or post processing tasks before a reload event and check included files.

BeforeReload Callback

<?php
$server->on('BeforeReload', function($serv, $workerId)
{
    var_dump(get_included_files());
});

Since version 4.5.0

Callback function before the code reloading event takes place.

AfterReload Callback

<?php
$server->on('AfterReload', function($serv, $workerId)
{
    var_dump(get_included_files());
});

Since version 4.5.0

Callback function when after the code reloading event takes place.

Server Modes and Reloading

A Swoole server can be started using two different modes, we have SWOOLE_PROCESS and SWOOLE_BASE, consider each mode when reloading files.

Process Mode

In process mode, multiple threads are started which manage different areas of the Swoole server, we have a Master (main) process, a manager process which handles all the worker tasks. During a reload only the worker threads are restarted but only when they are not busy.

Base Mode

In base mode, because connections interact with the worker thread directly, if a reload happens the connect is cut off and thus, a graceful restart won't happen in this server mode. Also base mode does not support reloading task workers.

Other information

Please visit the common questions page for more comments on hot reloading.

You could use addListener to add another port for the server to use and listen for server reload events so that you can externally reload the server and then use $server->reload().

Last updated on August 31, 2022