From fc6b607f630e58b9f8fa29af7569482751342d12 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Mon, 31 Aug 2026 14:10:47 +0200 Subject: [PATCH] swoole: optimize the event documentation --- reference/swoole/swoole.event.xml | 81 +++++++++++++++- reference/swoole/swoole/event/add.xml | 80 +++++++++++----- reference/swoole/swoole/event/cycle.xml | 102 +++++++++++++++++++++ reference/swoole/swoole/event/defer.xml | 47 +++++++--- reference/swoole/swoole/event/del.xml | 36 ++++---- reference/swoole/swoole/event/dispatch.xml | 68 ++++++++++++++ reference/swoole/swoole/event/exit.xml | 55 ----------- reference/swoole/swoole/event/isset.xml | 98 ++++++++++++++++++++ reference/swoole/swoole/event/set.xml | 93 +++++++++++++------ reference/swoole/swoole/event/wait.xml | 42 ++++++--- reference/swoole/swoole/event/write.xml | 87 ++++++++++++++---- 11 files changed, 616 insertions(+), 173 deletions(-) create mode 100644 reference/swoole/swoole/event/cycle.xml create mode 100644 reference/swoole/swoole/event/dispatch.xml delete mode 100644 reference/swoole/swoole/event/exit.xml create mode 100644 reference/swoole/swoole/event/isset.xml diff --git a/reference/swoole/swoole.event.xml b/reference/swoole/swoole.event.xml index 3cfe77b30d..7407723a0a 100644 --- a/reference/swoole/swoole.event.xml +++ b/reference/swoole/swoole.event.xml @@ -1,5 +1,5 @@ - + @@ -11,11 +11,86 @@
&reftitle.intro; - + + Модуль Swoole предоставляет низкоуровневые интерфейсы, чтобы напрямую + управлять нижележащим циклом событий epoll/kqueue/poll/select. + Он позволяет добавлять в цикл событий Swoole сокеты, которые создали + другие модули или модули PHP для работы с потоками и сокетами. + + + + Модуль Event — низкоуровневый, он представляет собой базовую обёртку + над epoll. Пользователю потребуется опыт программирования + с мультиплексированием ввода-вывода. + + +
+ +
+ Приоритет событий + + Функции обработки сигналов, которые задали методом Process::signal + Функции обратного вызова таймеров, которые задали методами Timer::tick и Timer::after + Отложенные функции, которые задали методом Event::defer + Периодические функции обратного вызова, которые задали методом Event::cycle + +
+ +
+ Типы сокетов событий Swoole + + + + + fd + int + + + + Файловые дескрипторы, включая Swoole\Client->$sock, Swoole\Process->$pipe + и любой другой файловый дескриптор (fd). + + + + + + stream resource + resource + + + + Ресурсы, которые создали функции stream_socket_client и fsockopen. + + + + + + socket resource + resource + + + + Ресурсам, которые создала функция socket_create модуля sockets, + требуется флаг --enable-sockets при компиляции Swoole. + + + + + + object + object + + + + Swoole автоматически преобразует Swoole\Process в UnixSocket, + а Swoole\Client — в подключённые клиентские сокеты на нижнем уровне. + + + +
-
&reftitle.classsynopsis; diff --git a/reference/swoole/swoole/event/add.xml b/reference/swoole/swoole/event/add.xml index 86282c811c..8af5491352 100644 --- a/reference/swoole/swoole/event/add.xml +++ b/reference/swoole/swoole/event/add.xml @@ -1,61 +1,70 @@ - + Swoole\Event::add - Добавляет новые callback-функции сокета в EventLoop + Добавляет сокет к нижележащему обработчику событий реактора &reftitle.description; public static boolSwoole\Event::add - intfd + mixedsock callableread_callback callablewrite_callback - stringevents + intflags - - - - + + Метод добавляет сокет к нижележащему обработчику событий реактора. + Метод вызывают и в режиме сервера, и в режиме клиента. + + + + Сокет, который уже добавили, добавить повторно нельзя. Чтобы изменить + соответствующие функции обратного вызова и типы событий сокета, вызывают + функцию swoole_event_set. + + &reftitle.parameters; - fd + sock - - - + + Файловый дескриптор, ресурс потока, ресурс сокета или объект. + read_callback - - - + + Функция обратного вызова для событий чтения. + write_callback - - - + + Функция обратного вызова для событий записи. + - events + flags - - - + + Маска типов событий, например SWOOLE_EVENT_READ, + SWOOLE_EVENT_WRITE или + SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE. + @@ -63,13 +72,36 @@ &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + Пример использования метода <function>Swoole\Event::add</function> + + +]]> + + - - + + + + + Swoole\Event::cycle + Задаёт функцию, которую выполняют в конце каждой итерации цикла событий + + + + &reftitle.description; + + public static boolSwoole\Event::cycle + callablecallback + boolbeforefalse + + + Метод задаёт функцию обратного вызова, которую выполняют в конце каждой + итерации цикла событий, а если параметру before + передали значение true — то в начале. + + + + + &reftitle.parameters; + + + callback + + + Функция, которую требуется выполнять. Значение null + убирает функцию, которую задали раньше. + + + + + before + + + Со значением true функцию выполняют до цикла событий, + со значением false — после. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + Базовый пример использования + + + + + + + + + diff --git a/reference/swoole/swoole/event/defer.xml b/reference/swoole/swoole/event/defer.xml index 8bb42e8d08..7d7265b0ae 100644 --- a/reference/swoole/swoole/event/defer.xml +++ b/reference/swoole/swoole/event/defer.xml @@ -1,33 +1,35 @@ - + Swoole\Event::defer - Добавляет callback-функцию в следующий цикл событий + Выполняет функцию в начале следующего цикла событий &reftitle.description; public static voidSwoole\Event::defer - mixedcallback + callablecallback_function - - - - + + Метод планирует функцию, которую выполнят в начале следующей итерации + цикла событий. + &reftitle.parameters; - callback + callback_function - - - + + Функция обратного вызова, которую требуется выполнить; параметры + не допускаются, переменные передают в замыкание конструкцией + use. + @@ -35,13 +37,30 @@ &reftitle.returnvalues; - + + Метод не возвращает значения. + + + + &reftitle.examples; + + + Пример использования метода <function>Swoole\Event::defer</function> + + +]]> + + - - + + Swoole\Event::del - Удаляет все callback-функции события сокета + Убирает сокет из обработчика событий реактора &reftitle.description; public static boolSwoole\Event::del - stringfd + mixedsock - - - - + + Метод убирает сокет из обработчика событий реактора. + + + + Перед закрытием сокета всегда вызывают метод Event::del, чтобы отменить + слежение за событиями. Иначе возникают утечки памяти. + + &reftitle.parameters; - fd + sock - - - + + Файловый дескриптор сокета, который требуется убрать. + @@ -36,13 +41,12 @@ &reftitle.returnvalues; - - - + + &return.success; + - - + + + + + Swoole\Event::dispatch + Выполняет одну итерацию цикла событий + + + + &reftitle.description; + + public static voidSwoole\Event::dispatch + + + + Метод нужен ради совместимости с рядом фреймворков. + Когда фреймворк сам управляет собственным циклом реактора, вызов метода + Event::wait оставил бы управление за нижним уровнем Swoole и не дал бы + фреймворку перехватить выполнение. + + + + + &reftitle.returnvalues; + + Метод не возвращает значения. + + + + + &reftitle.examples; + + + Ручное управление циклом событий + + + + + + + + + diff --git a/reference/swoole/swoole/event/exit.xml b/reference/swoole/swoole/event/exit.xml deleted file mode 100644 index 496ad573de..0000000000 --- a/reference/swoole/swoole/event/exit.xml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - Swoole\Event::exit - Выходит из цикла событий, доступно только на стороне клиента - - - - &reftitle.description; - - public static voidSwoole\Event::exit - - - - - - - - - - &reftitle.parameters; - &no.function.parameters; - - - - &reftitle.returnvalues; - - - - - - - - diff --git a/reference/swoole/swoole/event/isset.xml b/reference/swoole/swoole/event/isset.xml new file mode 100644 index 0000000000..4676e7af2f --- /dev/null +++ b/reference/swoole/swoole/event/isset.xml @@ -0,0 +1,98 @@ + + + + + + Swoole\Event::isset + Проверяет, следят ли за сокетом в цикле событий + + + + &reftitle.description; + + public static boolSwoole\Event::isset + mixedfd + intevents + + SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE + + + + + Метод проверяет, следят ли в цикле событий за указанным файловым + дескриптором для заданных типов событий. + + + + + &reftitle.parameters; + + + fd + + + Файловый дескриптор: ресурс потока или сокета, целое число либо объект. + + + + + events + + + Типы событий, которые требуется проверить: битовая маска из констант + SWOOLE_EVENT_READ и SWOOLE_EVENT_WRITE. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + Проверка того, следят ли за событиями + + + + + + + + + diff --git a/reference/swoole/swoole/event/set.xml b/reference/swoole/swoole/event/set.xml index ad8143f9f8..4b600272ac 100644 --- a/reference/swoole/swoole/event/set.xml +++ b/reference/swoole/swoole/event/set.xml @@ -1,61 +1,97 @@ - + Swoole\Event::set - Обновляет callback-функции события сокета + Изменяет функции обратного вызова и маску слежения за событиями &reftitle.description; public static boolSwoole\Event::set - intfd - stringread_callback - stringwrite_callback - stringevents + mixedsock + callableread_callback + callablewrite_callback + intflags - - - - + + Метод изменяет функции обратного вызова и маску слежения за событиями + для заданного файлового дескриптора. + + + + Когда параметр $read_callback не равен null, функцию обратного вызова + для событий чтения меняют на указанную функцию. + + + + + Когда параметр $write_callback не равен null, функцию обратного вызова + для событий записи меняют на указанную функцию. + + + + + Установка только константы SWOOLE_EVENT_READ отключает слежение + за событиями записи, а установка только константы SWOOLE_EVENT_WRITE + отключает слежение за событиями чтения. + + + + + Метод Swoole\Event::set заменяет функции обратного вызова, но не + освобождает их. Значение null для функций обратного вызова, то есть + для параметров read_callback и write_callback, сохраняет существующие + функции, а не очищает их. + + + + + Слежение за константой SWOOLE_EVENT_READ без параметра read_callback + или за константой SWOOLE_EVENT_WRITE без параметра write_callback + приводит к неудаче операции и возврату значения false. + + &reftitle.parameters; - fd + sock - - - + + Файловый дескриптор, ресурс потока, ресурс сокета или объект. + read_callback - - - + + Функция обратного вызова для событий чтения. + write_callback - - - + + Функция обратного вызова для событий записи. + - events + flags - - - + + Маска типов событий, например SWOOLE_EVENT_READ, + SWOOLE_EVENT_WRITE или + SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE. + @@ -63,13 +99,12 @@ &reftitle.returnvalues; - - - + + &return.success; + - - + + + Swoole\Event::wait - Описание + Запускает цикл событий @@ -13,28 +14,39 @@ public static voidSwoole\Event::wait - - - - - &warn.undocumented.func; - - - - - &reftitle.parameters; - &no.function.parameters; + + Метод запускает цикл событий. Его размещают в конце PHP-программы. + &reftitle.returnvalues; + + Метод не возвращает значения. + + + + + &reftitle.examples; + + Пример использования метода <function>Swoole\Event::wait</function> + + +]]> + + - - + + + Swoole\Event::write - Записывает данные в сокет + Асинхронно записывает данные в сокет &reftitle.description; - public static voidSwoole\Event::write - stringfd - stringdata + public static boolSwoole\Event::write + mixedfd + mixeddata - - - - + + Метод делает отправку данных асинхронной для ресурсов потоков и сокетов. + + + + Если данные непрерывно пишут в сокет, а принимающая сторона не успевает + их читать, буфер сокета в итоге заполнится. В этом случае нижний уровень + Swoole сохранит лишние данные в буфере в памяти и подождёт события + готовности к записи, прежде чем снова попытаться писать в сокет. Однако, + если буфер в памяти тоже заполнится, Swoole выбросит ошибку + «pipe buffer overflow, reactor will block» и переключится в блокирующий + режим, приостановив дальнейшую запись, пока не освободится место. + + + + + Возврат значения false при заполненном буфере — атомарная операция: + она гарантирует либо полный успех, когда записали все данные, либо + полную неудачу, когда не записали ничего. + + + + + Метод Event::write нельзя применять к потокам и сокетам, которые + зашифровали по SSL/TLS, то есть к туннелированным соединениям. + + + + + При успешном выполнении метод Event::write автоматически переключает + сокет $socket в неблокирующий режим. + + @@ -26,17 +56,18 @@ fd - - - + + Файловый дескриптор: ресурс потока или сокета, целое число либо объект. + data - - - + + Данные, которые требуется отправить; их длина не должна превышать + размер буфера сокета. + @@ -44,13 +75,35 @@ &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + Пример использования метода <function>Swoole\Event::write</function> + + +]]> + + - - +