[DOC-CVS] [doc-en] master: Add swoole coroutine hook docs (#4775)

Author: MARiA so cute (NathanFreeman)
Committer: GitHub (web-flow)
Pusher: sy-records
Date: 2025-07-14T16:22:54+08:00

Commit: https://github.com/php/doc-en/commit/f03cb84c37d21f3e827ecb737ca7a3fd5fce1b7b
Raw diff: https://github.com/php/doc-en/commit/f03cb84c37d21f3e827ecb737ca7a3fd5fce1b7b.diff

Add swoole coroutine hook docs (#4775)

Co-authored-by: Luffy <[email protected]>

Changed paths:
  A  reference/swoole/swoole.runtime.xml
  A  reference/swoole/swoole/runtime/enableCoroutine.xml
  A  reference/swoole/swoole/runtime/getHookFlags.xml
  A  reference/swoole/swoole/runtime/setHookFlags.xml
  M  reference/swoole/book.xml


Diff:

diff --git a/reference/swoole/book.xml b/reference/swoole/book.xml
index c91dba43c695..fe0f4feeeff3 100644
--- a/reference/swoole/book.xml
+++ b/reference/swoole/book.xml
@@ -50,6 +50,7 @@
  &reference.swoole.swoole.mysql.exception;
  &reference.swoole.swoole.process;
  &reference.swoole.swoole.redis.server;
+ &reference.swoole.swoole.runtime;
  &reference.swoole.swoole.serialize;
  &reference.swoole.swoole.server;
  <!-- &reference.swoole.swoole.server.port; -->
diff --git a/reference/swoole/swoole.runtime.xml b/reference/swoole/swoole.runtime.xml
new file mode 100644
index 000000000000..d96fd45b94e6
--- /dev/null
+++ b/reference/swoole/swoole.runtime.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<reference xml:id="class.swoole-runtime" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The Swoole\Runtime class</title>
+ <titleabbrev>Swoole\Runtime</titleabbrev>
+
+ <partintro>
+
+  <!-- {{{ Swoole\Runtime intro -->
+  <section xml:id="swoole-runtime.intro">
+   &reftitle.intro;
+   <para>
+    Swoole\Runtime provides coroutine support for various PHP functions through hook mechanism,
+    allowing synchronous code to work asynchronously in coroutine environment.
+   </para>
+  </section>
+  <!-- }}} -->
+
+  <section xml:id="swoole-runtime.synopsis">
+   &reftitle.classsynopsis;
+
+   <!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>Swoole\Runtime</classname></ooclass>
+
+    <!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>Swoole\Runtime</classname>
+     </ooclass>
+    </classsynopsisinfo>
+    <!-- }}} -->
+
+    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.swoole-runtime')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
+   </classsynopsis>
+   <!-- }}} -->
+
+  </section>
+
+ </partintro>
+
+ &reference.swoole.swoole.entities.runtime;
+
+</reference>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/runtime/enableCoroutine.xml b/reference/swoole/swoole/runtime/enableCoroutine.xml
new file mode 100644
index 000000000000..79e6dc613153
--- /dev/null
+++ b/reference/swoole/swoole/runtime/enableCoroutine.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-runtime.enable-coroutine" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Swoole\Runtime::enableCoroutine</refname>
+  <refpurpose>Enable coroutine for specified functions</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Runtime::enableCoroutine</methodname>
+   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>SWOOLE_HOOK_ALL</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   This method enables coroutine support for specified PHP functions based on the given flags.
+   It should be called once at the beginning of the application.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>flags</parameter></term>
+    <listitem>
+     <para>
+      Bitmask of flags specifying which functions to hook. Can be combined using | operator.
+      Available flags:
+      <constant>SWOOLE_HOOK_TCP</constant>,
+      <constant>SWOOLE_HOOK_UDP</constant>,
+      <constant>SWOOLE_HOOK_UNIX</constant>,
+      <constant>SWOOLE_HOOK_UDG</constant>,
+      <constant>SWOOLE_HOOK_SSL</constant>,
+      <constant>SWOOLE_HOOK_TLS</constant>,
+      <constant>SWOOLE_HOOK_SLEEP</constant>,
+      <constant>SWOOLE_HOOK_FILE</constant>,
+      <constant>SWOOLE_HOOK_STREAM_FUNCTION</constant>,
+      <constant>SWOOLE_HOOK_BLOCKING_FUNCTION</constant>,
+      <constant>SWOOLE_HOOK_PROC</constant>,
+      <constant>SWOOLE_HOOK_CURL</constant>,
+      <constant>SWOOLE_HOOK_NATIVE_CURL</constant>,
+      <constant>SWOOLE_HOOK_SOCKETS</constant>,
+      <constant>SWOOLE_HOOK_STDIO</constant>,
+      <constant>SWOOLE_HOOK_PDO_PGSQL</constant>,
+      <constant>SWOOLE_HOOK_PDO_ODBC</constant>,
+      <constant>SWOOLE_HOOK_PDO_ORACLE</constant>,
+      <constant>SWOOLE_HOOK_PDO_SQLITE</constant>,
+      or <constant>SWOOLE_HOOK_ALL</constant> for all flags.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </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
+-->
diff --git a/reference/swoole/swoole/runtime/getHookFlags.xml b/reference/swoole/swoole/runtime/getHookFlags.xml
new file mode 100644
index 000000000000..93b37eb271fb
--- /dev/null
+++ b/reference/swoole/swoole/runtime/getHookFlags.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-runtime.get-hook-flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Swoole\Runtime::getHookFlags</refname>
+  <refpurpose>Get current hook flags</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Swoole\Runtime::getHookFlags</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   Gets the current hook flags.
+   Note that the returned flags might differ from what was set if some hooks failed.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   This function has no parameters.
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the current hook flags as a bitmask.
+  </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
+-->
diff --git a/reference/swoole/swoole/runtime/setHookFlags.xml b/reference/swoole/swoole/runtime/setHookFlags.xml
new file mode 100644
index 000000000000..6f9052c3d651
--- /dev/null
+++ b/reference/swoole/swoole/runtime/setHookFlags.xml
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-runtime.set-hook-flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Swoole\Runtime::setHookFlags</refname>
+  <refpurpose>Set hook flags for coroutine</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Runtime::setHookFlags</methodname>
+   <methodparam><type>int</type><parameter>flags</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Sets the hook flags for coroutine support.
+   This dynamically changes the hook flags at runtime.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>flags</parameter></term>
+    <listitem>
+     <para>
+      Bitmask of flags specifying which functions to hook. Same flags as enableCoroutine.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </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
+-->