Skip to content

optimize swoole event docs #4774

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

Merged
jordikroon merged 3 commits into from
Aug 12, 2026
Merged

optimize swoole event docs #4774

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c3b7969
optimize swoole event
NathanFreeman Jul 12, 2025
dd84b8d
apply CS fixes
jordikroon Aug 12, 2026
c273e1a
apply CS fixes
jordikroon Aug 12, 2026
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
74 changes: 72 additions & 2 deletions reference/swoole/swoole.event.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,81 @@
<!-- {{{ Swoole\Event intro -->
<section xml:id="swoole-event.intro">
&reftitle.intro;
<para>
<simpara>
The Swoole extension provides low-level interfaces to directly manipulate the underlying epoll/kqueue/poll/select event loop.
It allows adding sockets created by other extensions or PHP's stream/socket extensions to Swoole's EventLoop.
</simpara>
<note>
<simpara>
The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming.
</simpara>
</note>
</section>
<!-- }}} -->

<section xml:id="swoole-event.event-priority">
<title>Event Priority</title>
<orderedlist>
<listitem><simpara>Signal handler callback functions set via Process::signal</simpara></listitem>
<listitem><simpara>Timer callback functions set via Timer::tick and Timer::after</simpara></listitem>
<listitem><simpara>Deferred execution functions set via Event::defer</simpara></listitem>
<listitem><simpara>Periodic callback functions set via Event::cycle</simpara></listitem>
</orderedlist>
</section>

<section xml:id="swoole-event.event-socket">
<title>Swoole Event Socket Type</title>
<para>
<variablelist>
<varlistentry xml:id="swoole-event.int">
<term>
<parameter>fd</parameter>
<type>int</type>
</term>
<listitem>
<simpara>
File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.stream">
<term>
<parameter>stream resource</parameter>
<type>resource</type>
</term>
<listitem>
<simpara>
Resources created by stream_socket_client/fsockopen.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.socket">
<term>
<parameter>socket resource</parameter>
<type>resource</type>
</term>
<listitem>
<simpara>
Resources created by socket_create from the sockets extension require
the --enable-sockets flag during Swoole compilation.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.object">
<term>
<parameter>object</parameter>
<type>object</type>
</term>
<listitem>
<simpara>
Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client
into connected client sockets at the underlying level.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<!-- }}} -->

<section xml:id="swoole-event.synopsis">
&reftitle.classsynopsis;
Expand Down
77 changes: 52 additions & 25 deletions reference/swoole/swoole/event/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,100 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<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>Add new callback functions of a socket into the EventLoop.</refpurpose>
<refpurpose>Add a socket to the underlying reactor event listener</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::add</methodname>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::add</methodname>
<modifier>public</modifier> <modifier>static</modifier> <type
class="union"><type>false</type><type>int</type></type><methodname>Swoole\Event::add</methodname>

<methodparam><type>int</type><parameter>fd</parameter></methodparam>
<methodparam><type>mixed</type><parameter>sock</parameter></methodparam>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam><type>mixed</type><parameter>sock</parameter></methodparam>
<methodparam><type>mixed</type><parameter>fd</parameter></methodparam>

<methodparam><type>callable</type><parameter>read_callback</parameter></methodparam>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam><type>callable</type><parameter>read_callback</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>read_callback</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>callable</type><parameter>write_callback</parameter></methodparam>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam choice="opt"><type>callable</type><parameter>write_callback</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>write_callback</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>events</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>events</parameter><initializer>SWOOLE_EVENT_READ</initializer></methodparam>

</methodsynopsis>
<para>

</para>

<simpara>
Adds a socket to the underlying reactor event listener. This function can be used in both Server and Client modes.
</simpara>
<warning>
<simpara>
A socket that has already been added cannot be added again. Use swoole_event_set to
modify the corresponding callback functions and event types for the socket.
</simpara>
</warning>
</refsect1>

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

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<term><parameter>sock</parameter></term>
<term><parameter>fd</parameter></term>

<listitem>
<para>

</para>
<simpara>
File descriptor, stream resource, sockets resource, or object.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>read_callback</parameter></term>
<listitem>
<para>

</para>
<simpara>
Callback function for readable events.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>write_callback</parameter></term>
<listitem>
<para>

</para>
<simpara>
Callback function for writable events.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>events</parameter></term>
<term><parameter>flags</parameter></term>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<term><parameter>flags</parameter></term>
<term><parameter>events</parameter></term>

<listitem>
<para>

</para>
<simpara>
Event type mask (e.g. <constant>SWOOLE_EVENT_READ</constant>, <constant>SWOOLE_EVENT_WRITE</constant>
or <constant>SWOOLE_EVENT_READ</constant> | <constant>SWOOLE_EVENT_WRITE</constant>).
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

</para>
<simpara>
&return.success;
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>Swoole\Event::add</function> example</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
Expand Down
97 changes: 97 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,97 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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>Define a function to execute at the end of each event loop iteration</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>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>before</parameter><initializer>false</initializer></methodparam>
</methodsynopsis>
<simpara>
Defines a callback function to execute at the end (or beginning, if <parameter>before</parameter> is true) of each event loop iteration.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<simpara>
The function to execute. Set to <literal>null</literal> to clear a previously set cycle function.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>before</parameter></term>
<listitem>
<simpara>
If <literal>true</literal>, the callback executes before the event loop; if <literal>false</literal>, after.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

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

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Basic usage</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
-->
42 changes: 28 additions & 14 deletions reference/swoole/swoole/event/defer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,60 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="swoole-event.defer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Event::defer</refname>
<refpurpose>Add a callback function to the next event loop.</refpurpose>
<refpurpose>Execute a function at the start of the next event loop</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::defer</methodname>

@lacatoire lacatoire Jun 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::defer</methodname>
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::defer</methodname>

<methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback_function</parameter></methodparam>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<methodparam><type>callable</type><parameter>callback_function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>

</methodsynopsis>
<para>

</para>

<simpara>
Schedules a function to run at the start of the next event loop iteration.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>callback</parameter></term>
<term><parameter>callback_function</parameter></term>

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<term><parameter>callback_function</parameter></term>
<term><parameter>callback</parameter></term>

<listitem>
<para>

</para>
<simpara>
Callback function to execute (no parameters allowed; use <literal>use</literal> for closure variables).
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
No return value.

@lacatoire lacatoire Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
No return value.
&return.success;

</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>

<example>
<title><function>Swoole\Event::defer</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
Swoole\Event::defer(function(){
echo "After EventLoop\n";
});
?>
]]>
</programlisting>
</example>
</para>
</refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Expand Down
Loading