Skip to content

[Sync-EN] Optimize the Swoole event documentation #1806

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[Sync-EN] Optimize the Swoole event documentation #1806

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 78 additions & 3 deletions reference/swoole/swoole.event.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 322606e4f1742a6f959e952c63fb1f8bcd6d6ba0 Maintainer: sergey Status: ready -->
<!-- EN-Revision: 282797eedc7c7bca6a6f55a9aad32b135feb3320 Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->
<reference xml:id="class.swoole-event" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

Expand All @@ -11,11 +11,86 @@
<!-- {{{ Swoole\Event intro -->
<section xml:id="swoole-event.intro">
&reftitle.intro;
<para>
<simpara>
Модуль Swoole предоставляет низкоуровневые интерфейсы, чтобы напрямую
управлять нижележащим циклом событий epoll/kqueue/poll/select.
Он позволяет добавлять в цикл событий Swoole сокеты, которые создали
другие модули или модули PHP для работы с потоками и сокетами.
</simpara>
<note>
<simpara>
Модуль Event — низкоуровневый, он представляет собой базовую обёртку
над epoll. Пользователю потребуется опыт программирования
с мультиплексированием ввода-вывода.
</simpara>
</note>
</section>
<!-- }}} -->

<section xml:id="swoole-event.event-priority">
<title>Приоритет событий</title>
<orderedlist>
<listitem><simpara>Функции обработки сигналов, которые задали методом Process::signal</simpara></listitem>
<listitem><simpara>Функции обратного вызова таймеров, которые задали методами Timer::tick и Timer::after</simpara></listitem>
<listitem><simpara>Отложенные функции, которые задали методом Event::defer</simpara></listitem>
<listitem><simpara>Периодические функции обратного вызова, которые задали методом Event::cycle</simpara></listitem>
</orderedlist>
</section>

<section xml:id="swoole-event.event-socket">
<title>Типы сокетов событий Swoole</title>
<para>
<variablelist>
<varlistentry xml:id="swoole-event.int">
<term>
<parameter>fd</parameter>
<type>int</type>
</term>
<listitem>
<simpara>
Файловые дескрипторы, включая Swoole\Client->$sock, Swoole\Process->$pipe
и любой другой файловый дескриптор (fd).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.stream">
<term>
<parameter>stream resource</parameter>
<type>resource</type>
</term>
<listitem>
<simpara>
Ресурсы, которые создали функции stream_socket_client и fsockopen.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.socket">
<term>
<parameter>socket resource</parameter>
<type>resource</type>
</term>
<listitem>
<simpara>
Ресурсам, которые создала функция socket_create модуля sockets,
требуется флаг --enable-sockets при компиляции Swoole.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.object">
<term>
<parameter>object</parameter>
<type>object</type>
</term>
<listitem>
<simpara>
Swoole автоматически преобразует Swoole\Process в UnixSocket,
а Swoole\Client — в подключённые клиентские сокеты на нижнем уровне.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<!-- }}} -->

<section xml:id="swoole-event.synopsis">
&reftitle.classsynopsis;
Expand Down
80 changes: 56 additions & 24 deletions reference/swoole/swoole/event/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,107 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: sergey Status: ready -->
<!-- EN-Revision: 282797eedc7c7bca6a6f55a9aad32b135feb3320 Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="swoole-event.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Event::add</refname>
<refpurpose>Добавляет новые callback-функции сокета в EventLoop</refpurpose>
<refpurpose>Добавляет сокет к нижележащему обработчику событий реактора</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::add</methodname>
<methodparam><type>int</type><parameter>fd</parameter></methodparam>
<methodparam><type>mixed</type><parameter>sock</parameter></methodparam>
<methodparam><type>callable</type><parameter>read_callback</parameter></methodparam>
<methodparam choice="opt"><type>callable</type><parameter>write_callback</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>events</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>

</para>

<simpara>
Метод добавляет сокет к нижележащему обработчику событий реактора.
Метод вызывают и в режиме сервера, и в режиме клиента.
</simpara>
<warning>
<simpara>
Сокет, который уже добавили, добавить повторно нельзя. Чтобы изменить
соответствующие функции обратного вызова и типы событий сокета, вызывают
функцию swoole_event_set.
</simpara>
</warning>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<term><parameter>sock</parameter></term>
<listitem>
<para>

</para>
<simpara>
Файловый дескриптор, ресурс потока, ресурс сокета или объект.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>read_callback</parameter></term>
<listitem>
<para>

</para>
<simpara>
Функция обратного вызова для событий чтения.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write_callback</parameter></term>
<listitem>
<para>

</para>
<simpara>
Функция обратного вызова для событий записи.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>events</parameter></term>
<term><parameter>flags</parameter></term>
<listitem>
<para>

</para>
<simpara>
Маска типов событий, например <constant>SWOOLE_EVENT_READ</constant>,
<constant>SWOOLE_EVENT_WRITE</constant> или
<constant>SWOOLE_EVENT_READ</constant> | <constant>SWOOLE_EVENT_WRITE</constant>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
&return.success;
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Пример использования метода <function>Swoole\Event::add</function></title>
<programlisting role="php">
<![CDATA[
<?php
$fp = stream_socket_client("tcp://www.qq.com:80", $errno, $errstr, 30);
fwrite($fp,"GET / HTTP/1.1\r\nHost: www.qq.com\r\n\r\n");

Swoole\Event::add($fp, function($fp) {
$resp = fread($fp, 8192);
Swoole\Event::del($fp);
fclose($fp);
});
echo "Finish\n";
?>
]]>
</programlisting>
</example>
</para>
</refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
102 changes: 102 additions & 0 deletions reference/swoole/swoole/event/cycle.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 282797eedc7c7bca6a6f55a9aad32b135feb3320 Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="swoole-event.cycle" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Event::cycle</refname>
<refpurpose>Задаёт функцию, которую выполняют в конце каждой итерации цикла событий</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::cycle</methodname>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>before</parameter><initializer>false</initializer></methodparam>
</methodsynopsis>
<simpara>
Метод задаёт функцию обратного вызова, которую выполняют в конце каждой
итерации цикла событий, а если параметру <parameter>before</parameter>
передали значение true — то в начале.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<simpara>
Функция, которую требуется выполнять. Значение <literal>null</literal>
убирает функцию, которую задали раньше.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>before</parameter></term>
<listitem>
<simpara>
Со значением <literal>true</literal> функцию выполняют до цикла событий,
со значением <literal>false</literal> — после.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
&return.success;
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Базовый пример использования</title>
<programlisting role="php">
<![CDATA[
<?php
Swoole\Timer::tick(2000, function ($id) {
var_dump($id);
});

Swoole\Event::cycle(function () {
echo "hello [1]\n";
Swoole\Event::cycle(function () {
echo "hello [2]\n";
Swoole\Event::cycle(null);
});
});

Swoole\Event::wait();
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Loading
Loading