Understanding Swoole Coroutines and Asynchronous I/O in PHP

Many PHP developers encounter Swoole for the first time and feel confused about its core concepts. Swoole introduces user‑level threads called coroutines, which run on a single OS thread, consume only memory, and can be created in massive numbers as long as sufficient memory is available.

In Swoole, coroutine switching is implemented via a dual‑stack mechanism (C stack and PHP stack) that operates entirely in user space, achieving nanosecond‑level context switches that are negligible compared to the actual business logic, especially in I/O‑heavy programs.

Coroutines should not be mistaken for a universal parallelism tool; they always run within a single thread, so they cannot perform true parallel computation without asynchronous network I/O support.

Coroutine

A coroutine can be viewed as a lightweight stack switcher: when a sub‑program yields, the runtime saves its execution point and later resumes it from the same location.

However, coroutine alone cannot achieve asynchronous behavior; without asynchronous network I/O, switching between coroutines merely adds overhead.

Asynchronous I/O

Note: The term “asynchronous I/O” in this article refers to the practical, everyday usage rather than the strict technical definition.

In Unix, what is often called asynchronous I/O is actually non‑blocking I/O combined with an event‑driven reactor model. True asynchronous I/O (e.g., Windows I/O Completion Ports) completes operations without the application ever entering the kernel for data transfer, while non‑blocking I/O still requires a read/write call after the socket becomes ready.

Blocking

Non‑Blocking

read, write

(read, write) + poll / select / epoll / kqueue

Asynchronous

-

aio_read, aio_write, IOCP (Windows)

The reactor model, illustrated in the image below, multiplexes many I/O sources so that the program only blocks when no I/O is ready, effectively hiding I/O latency from the CPU.

Coroutine + Asynchronous = Synchronous Non‑Blocking Programming

By combining coroutines with asynchronous I/O, developers can write code that looks synchronous while actually being non‑blocking. The pattern is simple: suspend the coroutine after issuing an asynchronous request, and resume it when the callback fires.

Swoole\Coroutine\run(function(){
    // 1. Create a timer and suspend coroutine #1
    Swoole\Coroutine::sleep(1);
    // 3. Coroutine resumes, continues execution, then yields again
});
// 2. Coroutine #1 yields, enters the event loop, timer fires after 1 s, resumes coroutine #1
// 4. Coroutine #1 exits, no more events, event loop ends, process terminates

A single Swoole\Coroutine::sleep(1) behaves like the traditional blocking sleep but does not block the whole process.

for ($n = 10; $n--;) {
    Swoole\Coroutine::create(function(){
        Swoole\Coroutine::sleep(1);
    });
}

Creating ten coroutines each sleeping one second results in the whole process blocking for only one second, demonstrating that I/O‑bound work becomes coroutine‑level blocking rather than process‑level.

Coroutine Coding Patterns

Timer Tasks

Using traditional timers inside coroutines often forces a new coroutine per tick and relies on global variables for context.

$stopTimer = false;
$timerContext = [];
$timerId = Swoole\Timer::tick(1, function(){
    global $timerContext, $timerId, $stopTimer;
    $timerContext[] = 'data';
    if ($stopTimer) {
        var_dump($timerContext);
        Swoole\Timer::clear($timerId);
    }
});
// To stop the timer later:
$stopTimer = true;

With coroutines, a channel can replace the global state, providing a clean, single‑coroutine implementation.

Swoole\Coroutine\run(function(){
    $channel = new Swoole\Coroutine\Channel;
    Swoole\Coroutine::create(function() use ($channel){
        $context = [];
        while (!$channel->pop(0.001)) {
            $context[] = 'data';
        }
        var_dump($context);
    });
    // Stop the timer by pushing a value
    $channel->push(true);
});

Task Processes

Historically, Swoole’s Task processes were meant for operations that could not be asynchronous, acting like a PHP‑FPM worker. Some developers mistakenly offload every task to the Task process, incurring extra serialization, IPC, and context‑switch overhead.

When using coroutines, the Task process should not be used for asynchronous work because the coroutine runtime already provides lightweight, non‑blocking execution.

$server->on('Receive', function (Swoole\Server $server) {
    // Submit a task, data is serialized and sent via IPC
    $task_id = $server->task('foo');
});
$server->on('Task', function (Swoole\Server $server, $task_id, $from_id, $data) {
    // Perform coroutine DNS lookup inside the task
    $result = \Swoole\Coroutine::gethostbyname($data);
    $server->finish($result);
});
$server->on('Finish', function (Swoole\Server $server, int $task_id, $result) {
    echo "Task#{$task_id} finished";
    var_dump($result);
});

Coroutine‑Based Task Execution

Using the library‑provided Coroutine\batch (or a manual channel‑based scheduler) allows concurrent DNS queries without any serialization or IPC cost.

use Swoole\Coroutine;
Coroutine\run(function(){
    $result = Coroutine\batch([
        '100tal' => function(){ return Coroutine::gethostbyname('www.100tal.com'); },
        'xueersi' => function(){ return Coroutine::gethostbyname('www.xueersi.com'); },
        'zhiyinlou' => function(){ return Coroutine::gethostbyname('www.zhiyinlou.com'); },
    ]);
    var_dump($result);
});

The output preserves the order of the input array, confirming that the API guarantees deterministic results despite the underlying asynchronous execution.

array(3) {
  ["100tal"]=> string(14) "203.107.33.189"
  ["xueersi"]=> string(12) "60.28.226.27"
  ["zhiyinlou"]=> string(14) "101.36.129.150"
}

In summary, coroutines extend traditional synchronous and non‑blocking techniques into a unified model: a single coroutine behaves synchronously, while multiple coroutines provide massive I/O concurrency without the pitfalls of callback hell.

By understanding these concepts, PHP developers can write high‑quality, maintainable, and highly performant backend services using Swoole.