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

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

optimize swoole event docs #4774

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
72 changes: 71 additions & 1 deletion reference/swoole/swoole.event.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,81 @@
<section xml:id="swoole-event.intro">
&reftitle.intro;
<para>

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>
<note>
<para>
The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming.
</para>
</note>
</section>
<!-- }}} -->

<section xml:id="swoole-event.event-priority">
<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>
<listitem><para>Deferred execution functions set via Event::defer</para></listitem>
<listitem><para>Periodic callback functions set via Event::cycle</para></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>
<para>
File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.stream">
<term>
<parameter>stream resource</parameter>
<type>resource</type>
</term>
<listitem>
<para>
Resources created by stream_socket_client/fsockopen.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.socket">
<term>
<parameter>socket resource</parameter>
<type>resource</type>
</term>
<listitem>
<para>
Resources created by socket_create from the sockets extension require
the --enable-sockets flag during Swoole compilation.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="swoole-event.object">
<term>
<parameter>object</parameter>
<type>object</type>
</term>
<listitem>
<para>
Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client
into connected client sockets at the underlying level.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>

<section xml:id="swoole-event.synopsis">
&reftitle.classsynopsis;

Expand Down
53 changes: 40 additions & 13 deletions reference/swoole/swoole/event/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,64 @@
<?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>
<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>

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

<warning>
<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>
</warning>
</refsect1>

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

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

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

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

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>
</listitem>
</varlistentry>
Expand All @@ -63,11 +68,33 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

&return.success;
</para>
</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>
<methodparam choice="opt"><type>bool</type><parameter>before</parameter><initializer>false</initializer></methodparam>
</methodsynopsis>
<para>
Defines a callback function to execute at the end (or beginning, if <parameter>before</parameter> is true) of each event loop iteration.
</para>
</refsect1>

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

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</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
-->
32 changes: 23 additions & 9 deletions reference/swoole/swoole/event/defer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,30 @@
<?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>
<methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback_function</parameter></methodparam>
</methodsynopsis>
<para>

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

</refsect1>

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

Callback function to execute (no parameters allowed; use <literal>use</literal> for closure variables).
</para>
</listitem>
</varlistentry>
Expand All @@ -36,11 +34,27 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

No return value.
</para>
</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