Swoole\Server->on('WorkerStart', fn)

1. Swoole
2. Swoole Docs
3. Server
4. Swoole\Server->on('WorkerStart', fn)

Notice: the documentation is suitable for PHP extension swoole until v4.7.1, we only support PHP extension openswoole from v4.7.1

Declaration

<?php
Swoole\Server->on('WorkerStart', callable $callback)

Parameters

event

The event callback name.

callback

Callable event function.

Return

success

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

Description

Execute the callback function when a new Worker Process is started by the Swoole server. This event is triggered when either a worker process starts or a task process starts as tasks are just a separate worker thread. A Swoole server has worker threads which handle the business logic of a server request and task workers which handle any server tasks which get passed to them.

You can check the type of Worker Process based on the value of $workerId, if $workerId >= $server->setting['worker_num'], the worker is a Task Worker Process otherwise it is a Worker Process which is responsible for processing requests from the server.

Any objects or variables created within the callback can be used during the lifecycle of the process. Both the Start event and WorkerStart are executed concurrently, there is no order.

You can use $server->taskworker to determine if the worker is a server request thread or just a task worker process, if it is a task worker then $server->taskworker will be set to true.

When setting up the server configuration, any increase with worker_num or task_worker_num will trigger this callback for each worker once, you should use the $workerId to manage each process.

There is no relationship between workerId and the main PID of the process.

Example

Before these examples, if you need to see how a full working server is setup see the onStart event.

You can use the WorkerStart event to modify the process name when a new worker process starts:

<?php
$server = new Swoole\Server("127.0.0.1", 9501, SWOOLE_PROCESS, SWOOLE_SOCK_TCP);

// This event callback gets passed the server object and the worker process ID (Not the PID)
$server->on('WorkerStart', function(Swoole\Server $server, int $workerId)
{
    global $argv;

    if($workerId >= $server->setting['worker_num'])
    {
        swoole_set_process_name("php {$argv[0]} task worker");
    }
    else
    {
        swoole_set_process_name("php {$argv[0]} event worker");
    }
});

Get a list of all the loaded files which are available to the worker processes.

<?php
$server = new Swoole\Server("127.0.0.1", 9501, SWOOLE_PROCESS, SWOOLE_SOCK_TCP);

$server->on('WorkerStart', function(Swoole\Server $server, int $workerId)
{
    var_dump(get_included_files());
});

Because Swoole is stateful and runs in memory, any code changes won't immediately take effect upon new server requests, you have to either restart the whole server (losing any connections) or use the Swoole server reload functionality to gracefully restart worker processes. That is why we can detect which files have been included with the WorkerStart event callback as shown above. So for any worker processes that are restarted due to code changes and server reload events, you must only use the PHP include and require keywords within the WorkerStart callback, this ensures each worker process has access to the same files when a server reload happens. Swoole cannot reload files that were included before this callback. For more information about server reloading, see here.

Inside the WorkerStart event function, Swoole will automatically create a coroutine context for you, if you have enabled coroutines.

Important

Because Swoole runs in memory and continues in a stateful manner, a worker process handles the server requests coming in, if a fatal error takes place, instead of crashing the server, Swoole will just restart the failed worker instead but be careful as any files, tasks, timers or shared objects within a failed/restarted worker process will be lost and will need to be created again.

Also, if fatal errors or calls to exit() keep occurring, it will lead to Swoole constantly restarting the worker process, even though this is great for recovering from a crashed state, you should fix why the errors happens instead of relying on this feature.