Event Loop API

The Swoole Event Loop

Most of the modules provided by Swoole like the Server already handle setting up and operating an event loop for you, so you don’t have to worry about managing an event loop by yourself but, Swoole also provides you with a direct event loop API so you can interface and build your own event loops.

How does it work

The Event loop module is a low level API based on epoll_wait, which is a Linux function which allows you to wait and access file descriptor (fd) events when they are ready, therefore, Swoole provides you with a file-based event loop. Reading from and writing to files, inter-process communication, network communication and device controls all rely on file I/O to operate and can be identified through file descriptors (‘fd’s). This means the event loop API can use epoll_wait to poll and wait for file descriptors to trigger an event like when data has become available to process or a network operation has completed, this all uses I/O.

All the Async I/O fds are managed by the Event Loop. The Event Loop waits for readable, writeable and timeouts of all the fds. When an event (or timeout) occurs, the epoll_wait function finishes and returns the result. Then the callback function can be executed to process the result sent from the Event Loop. Because the Swoole event loop is based off epoll_wait, it is very efficient compared to other event loop implementations as epoll_wait only returns the changed status of file descriptors that are registered with the event loop, cutting out any wasted resources and time.

Things to consider

When a large amount of fds are registered on the Event Loop, and a large number of events are generated (or returned) at the same time, the corresponding callback functions are executed one by one, this is because the event loop can only process one callback at a time.

You can use the Event Loop API to add event callback functions onto the main Event Loop in the process. This allows you to use the API to interact with low level functions like epoll/kqueue from PHP, because epoll is not supported on MacOS, when running Swoole on MacOS it uses kqueue to achieve similar functionality.

Before using this API, you have to understand how non-blocking I/O, I/O multiplexing and Event Loops work.

Only non-blocking I/O fds should be added to the event loop, blocking IO should not be added to the Event Loop. The Swoole event loop will manage all the I/O multiplexing system calls for you internally but you must make sure to only use I/O which can be monitored via fds or enable Swoole Coroutine Hooks to handle any blocking code that might be within the event loop. All you have to do is register I/O events using the event loop API at the PHP level.

It can be used to manage a socket created with stream/socket API with the Event Loop, enabling you to process the result of a socket event within a callback and let the event loop handle read and write events.

It is not recommend to use directly within your application.