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

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

Declaration

<?php
Swoole\Server->on('Task', 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 receiving a new server Task.

The event Task is emitted when a Worker Process sends task data to the Task Worker Process pool, the number of task processes are configured within the server configuration with task_worker_num.

The Task Worker Process receiving task data calls the callback function registered on the event Task.

When a Task Worker Process is processing the new task, it's status is changed to be busy and the status is changed to be idle when finishing the task. When a task worker is busy, they cannot process any new tasks until idle again.

Server methods which will trigger this event:

Example

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

$server->set([
    'worker_num'      => 2,
    'task_worker_num' => 4,
]);

$server->on('Receive', function (Swoole\Server $server, $fd, $reactorId, $data)
{
    echo "Received data: " . $data . "\n";
    $data    = trim($data);

    $server->task($data, -1, function (Swoole\Server $server, $task_id, $data)
    {
        echo "Task Callback: ";
        var_dump($task_id, $data);
    });

    $task_id = $server->task($data, 0);

    $server->send($fd, "New task started with id: $task_id\n");
});

$server->on('Task', function (Swoole\Server $server, $task_id, $reactorId, $data)
{
    echo "Task Worker Process received data";

    echo "#{$server->worker_id}\tonTask: [PID={$server->worker_pid}]: task_id=$task_id, data_len=" . strlen($data) . "." . PHP_EOL;

    $server->finish($data);
});

$server->on('Finish', function (Swoole\Server $server, $task_id, $data)
{
    echo "Task#$task_id finished, data_len=" . strlen($data) . PHP_EOL;
});

$server->on('workerStart', function ($server, $worker_id)
{
    if($worker_id >= $server->setting['worker_num'])
    {
        swoole_set_process_name("php {$argv[0]}: task_worker");
    }
    else
    {
        swoole_set_process_name("php {$argv[0]}: worker");
    }
});

$server->start();

The server example above starts with 2 workers and 4 task worker processes.

  • Swoole\Server $server: The Swoole server object
  • int $taskId: The task thread ID of the worker process
  • int $srcWorkerId: The worker process ID of the worker that sent the task data
  • mixed $data: The data which has been sent to the task worker

In the callback function registered for the Task event, the return value of this function is the result of the completed task that will be sent back to the Worker Process that started the task. You can also return the result of a task by calling Swoole\Server->finish().

When the worker process has received the task result, the event finish is triggered the callback function on event finish will be executed with the task data result.

If you have enabled coroutine support with task workers with the task_enable_coroutine server configuration, then the task will send its results (if any as it is not required to return a result) to the on Finish event callback.

For example, with task_enable_coroutine:

<?php
$server->on('Task', function(Swoole\Server $server, Swoole\Server\Task $task)
{
    // Show the task data
    var_dump($task);

    // Complete the task and return a result which will trigger the `Finish` event, running a task asynchronously
    $task->finish([123, 'hello']);
});

A return value from a task can be any non null PHP value.

If a fatal error occurs within a task, Swoole will terminate that process, restart it and discard the failed task and the restarted task worker will become idle again and start processing any new tasks in the queue.