optimize swoole event docs by NathanFreeman · Pull Request #4774 · php/doc-en

NathanFreeman · 2025-07-12T08:30:11Z

No description provided.

lacatoire · 2026-06-22T16:08:00Z

+   <para>
+    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.
+   </para>


Suggested change

<para>

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.

</para>

<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>

lacatoire · 2026-06-22T16:08:49Z

+  <para>
+   Defines a callback function to execute at the end (or beginning, if <parameter>before</parameter> is true) of each event loop iteration.
+  </para>


Suggested change

<para>

Defines a callback function to execute at the end (or beginning, if <parameter>before</parameter> is true) of each event loop iteration.

</para>

<simpara>

Defines a callback function to execute at the end (or beginning, if <parameter>before</parameter> is true) of each event loop iteration.

</simpara>

lacatoire · 2026-06-22T16:09:06Z

+     <para>
+      The function to execute. Set to <literal>null</literal> to clear a previously set cycle function.
+     </para>


Suggested change

<para>

The function to execute. Set to <literal>null</literal> to clear a previously set cycle function.

</para>

<simpara>

The function to execute. Set to <literal>null</literal> to clear a previously set cycle function.

</simpara>

lacatoire · 2026-06-22T16:09:17Z

+     <para>
+      If <literal>true</literal>, the callback executes before the event loop; if <literal>false</literal>, after.
+     </para>


Suggested change

<para>

If <literal>true</literal>, the callback executes before the event loop; if <literal>false</literal>, after.

</para>

<simpara>

If <literal>true</literal>, the callback executes before the event loop; if <literal>false</literal>, after.

</simpara>

lacatoire · 2026-06-22T16:09:31Z

+  <para>
+   &return.success;
+  </para>


Suggested change

<para>

&return.success;

</para>

<simpara>

&return.success;

</simpara>

lacatoire · 2026-06-22T16:10:59Z

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


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>

lacatoire · 2026-06-22T16:11:39Z

  &reftitle.description;
  <methodsynopsis>
-   <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::exit</methodname>
+   <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::dispatch</methodname>


Suggested change

<modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::dispatch</methodname>

<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::dispatch</methodname>

lacatoire · 2026-06-22T16:12:20Z

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


Suggested change

<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::isset</methodname>

<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::isset</methodname>

lacatoire · 2026-06-22T16:12:34Z

+  <para>
+   Checks whether the specified file descriptor is being monitored for the given event types in the event loop.
+  </para>


Suggested change

<para>

Checks whether the specified file descriptor is being monitored for the given event types in the event loop.

</para>

<simpara>

Checks whether the specified file descriptor is being monitored for the given event types in the event loop.

</simpara>

lacatoire · 2026-06-22T16:12:50Z

+     <para>
+      Event types to check (bitmask of <constant>SWOOLE_EVENT_READ</constant> and/or <constant>SWOOLE_EVENT_WRITE</constant>).
+     </para>


Suggested change

<para>

Event types to check (bitmask of <constant>SWOOLE_EVENT_READ</constant> and/or <constant>SWOOLE_EVENT_WRITE</constant>).

</para>

<simpara>

Event types to check (bitmask of <constant>SWOOLE_EVENT_READ</constant> and/or <constant>SWOOLE_EVENT_WRITE</constant>).

</simpara>

lacatoire · 2026-06-22T16:13:06Z

+  <para>
+   &return.success;
+  </para>


Suggested change

<para>

&return.success;

</para>

<simpara>

&return.success;

</simpara>

lacatoire · 2026-06-22T16:14:23Z

+       <para>
+        Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client
+        into connected client sockets at the underlying level.
+       </para>


Suggested change

<para>

Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client

into connected client sockets at the underlying level.

</para>

<simpara>

Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client

into connected client sockets at the underlying level.

</simpara>

lacatoire · 2026-06-22T16:14:36Z

+       <para>
+        Resources created by socket_create from the sockets extension require
+        the --enable-sockets flag during Swoole compilation.
+       </para>


Suggested change

<para>

Resources created by socket_create from the sockets extension require

the --enable-sockets flag during Swoole compilation.

</para>

<simpara>

Resources created by socket_create from the sockets extension require

the --enable-sockets flag during Swoole compilation.

</simpara>

lacatoire · 2026-06-22T16:14:48Z

+       <para>
+        Resources created by stream_socket_client/fsockopen.
+       </para>


Suggested change

<para>

Resources created by stream_socket_client/fsockopen.

</para>

<simpara>

Resources created by stream_socket_client/fsockopen.

</simpara>

lacatoire · 2026-06-22T16:15:03Z

+       <para>
+        File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd).
+       </para>


Suggested change

<para>

File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd).

</para>

<simpara>

File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd).

</simpara>

lacatoire · 2026-06-22T16:15:16Z

+    <para>
+     The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming.
+    </para>


Suggested change

<para>

The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming.

</para>

<simpara>

The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming.

</simpara>

lacatoire · 2026-06-22T16:15:24Z

@@ -12,11 +12,81 @@
  <section xml:id="swoole-event.intro">
   &reftitle.intro;
   <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:15:33Z

-
+    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.
   </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:15:49Z

  <para>
-
+   &return.success;
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:15:57Z

@@ -45,11 +69,32 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:17:17Z

+   <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Event::dispatch</methodname>
   <void />
  </methodsynopsis>
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:17:32Z

+   The purpose of this function is to maintain compatibility with some frameworks.
+   When a framework internally manages its own reactor loop, using Event::wait would allow
+   Swoole's underlying layer to retain control, preventing the framework from taking over execution.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:17:51Z

-   <methodparam choice="opt"><type>string</type><parameter>events</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
  </methodsynopsis>
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:17:58Z

  <para>
-
+   Adds a socket to the underlying reactor event listener. This function can be used in both Server and Client modes.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:19:26Z

-    <term><parameter>events</parameter></term>
+    <term><parameter>flags</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:19:34Z

-
+      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>).
     </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:20:08Z

@@ -63,11 +68,33 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:20:17Z

  <para>
-
+   &return.success;
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:21:01Z

   <varlistentry>
    <term><parameter>read_callback</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:46:27Z

   <varlistentry>
    <term><parameter>write_callback</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:46:36Z

     <para>
-
+      Callback function for writable events.
     </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:46:46Z

-    <term><parameter>events</parameter></term>
+    <term><parameter>flags</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:46:56Z

-
+      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>).
     </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:47:07Z

@@ -63,11 +91,9 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:47:14Z

  <para>
-
+   &return.success;
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:48:50Z

@@ -14,26 +13,36 @@
   <void />
  </methodsynopsis>
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:49:00Z

  <para>
-
+   Starts the event loop. Place this at the end of your PHP program.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:49:13Z


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


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:49:22Z

  <para>
-
+   No return value.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:50:23Z

-   <methodparam><type>string</type><parameter>data</parameter></methodparam>
+   <modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Event::write</methodname>
+   <methodparam><type>mixed</type><parameter>fd</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>data</parameter></methodparam>


Suggested change

<methodparam><type>mixed</type><parameter>data</parameter></methodparam>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

lacatoire · 2026-06-22T16:50:42Z

+   <methodparam><type>mixed</type><parameter>fd</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>data</parameter></methodparam>
  </methodsynopsis>
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:50:52Z

  <para>
-
+   Makes data sending asynchronous for stream/sockets resources.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:51:03Z

@@ -27,15 +51,15 @@
    <term><parameter>fd</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:51:12Z

     <para>
-
+      File descriptor (stream/socket resource, integer, or object).
     </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:51:22Z

   <varlistentry>
    <term><parameter>data</parameter></term>
    <listitem>
     <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:51:31Z

     <para>
-
+      Data to send (length must not exceed socket buffer size).
     </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:53:02Z

+  <section xml:id="swoole-event.event-priority">
+   <title>Event Priority</title>
+   <orderedlist>
+    <listitem><para>Signal handler callback functions set via Process::signal</para></listitem>


Suggested change

<listitem><para>Signal handler callback functions set via Process::signal</para></listitem>

<listitem><simpara>Signal handler callback functions set via Process::signal</simpara></listitem>

lacatoire · 2026-06-22T16:53:13Z

+   <title>Event Priority</title>
+   <orderedlist>
+    <listitem><para>Signal handler callback functions set via Process::signal</para></listitem>
+    <listitem><para>Timer callback functions set via Timer::tick and Timer::after</para></listitem>


Suggested change

<listitem><para>Timer callback functions set via Timer::tick and Timer::after</para></listitem>

<listitem><simpara>Timer callback functions set via Timer::tick and Timer::after</simpara></listitem>

lacatoire · 2026-06-22T16:53:24Z

+   <orderedlist>
+    <listitem><para>Signal handler callback functions set via Process::signal</para></listitem>
+    <listitem><para>Timer callback functions set via Timer::tick and Timer::after</para></listitem>
+    <listitem><para>Deferred execution functions set via Event::defer</para></listitem>


Suggested change

<listitem><para>Deferred execution functions set via Event::defer</para></listitem>

<listitem><simpara>Deferred execution functions set via Event::defer</simpara></listitem>

lacatoire · 2026-06-22T16:53:37Z

+    <listitem><para>Signal handler callback functions set via Process::signal</para></listitem>
+    <listitem><para>Timer callback functions set via Timer::tick and Timer::after</para></listitem>
+    <listitem><para>Deferred execution functions set via Event::defer</para></listitem>
+    <listitem><para>Periodic callback functions set via Event::cycle</para></listitem>


Suggested change

<listitem><para>Periodic callback functions set via Event::cycle</para></listitem>

<listitem><simpara>Periodic callback functions set via Event::cycle</simpara></listitem>

lacatoire · 2026-06-22T16:55:11Z

+   <methodparam choice="opt"><type>callable</type><parameter>write_callback</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
  </methodsynopsis>
  <para>


Suggested change

<para>

<simpara>

lacatoire · 2026-06-22T16:55:21Z

  <para>
-
+   Modifies the event listener callbacks and mask for the given file descriptor.
  </para>


Suggested change

</para>

</simpara>

lacatoire · 2026-06-22T16:55:38Z

   </varlistentry>
   <varlistentry>
-    <term><parameter>events</parameter></term>
+    <term><parameter>flags</parameter></term>


Suggested change

<term><parameter>flags</parameter></term>

<term><parameter>events</parameter></term>

jordikroon · 2026-08-12T19:57:02Z

Hi @NathanFreeman. Thank you for this PR.
I have looked into it, and changed some style violations and a missing reference &reference.swoole.swoole.event.exit; which what I can see is a removed file within the changes.

I have not looked at the accuracy of the changes, nor have I merged the suggested changes in. I suggest you to have a quick look at those, and present hem in a follow-up PR if required.

Over the next few months, we will be migrating this extension to https://github.com/php/doc-extensions per RFC. So any follow-up PRs will likely have to target that repository based on its state.

NathanFreeman force-pushed the event branch from 4d51840 to 9334486 Compare July 12, 2025 08:34

lacatoire reviewed Jun 22, 2026

View reviewed changes

NathanFreeman and others added 2 commits August 12, 2026 21:46

optimize swoole event

c3b7969

apply CS fixes

dd84b8d

jordikroon force-pushed the event branch from 9334486 to dd84b8d Compare August 12, 2026 19:48

apply CS fixes

c273e1a

jordikroon merged commit 282797e into php:master Aug 12, 2026
2 checks passed

	<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>data</parameter></methodparam>
	<methodparam><type>string</type><parameter>data</parameter></methodparam>

	<listitem><para>Signal handler callback functions set via Process::signal</para></listitem>
	<listitem><simpara>Signal handler callback functions set via Process::signal</simpara></listitem>

	<listitem><para>Timer callback functions set via Timer::tick and Timer::after</para></listitem>
	<listitem><simpara>Timer callback functions set via Timer::tick and Timer::after</simpara></listitem>

	<listitem><para>Deferred execution functions set via Event::defer</para></listitem>
	<listitem><simpara>Deferred execution functions set via Event::defer</simpara></listitem>

	<listitem><para>Periodic callback functions set via Event::cycle</para></listitem>
	<listitem><simpara>Periodic callback functions set via Event::cycle</simpara></listitem>

	<term><parameter>flags</parameter></term>
	<term><parameter>events</parameter></term>

Uh oh!

Conversation

NathanFreeman commented Jul 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lacatoire Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lacatoire Jun 22, 2026 •

edited

Loading