diff --git a/reference/swoole/swoole.event.xml b/reference/swoole/swoole.event.xml index 1e58ed1c711f..929af191148a 100644 --- a/reference/swoole/swoole.event.xml +++ b/reference/swoole/swoole.event.xml @@ -12,11 +12,81 @@
&reftitle.intro; - + 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. + + + The Event module is low-level, being a basic encapsulation of epoll. Users should have experience with IO multiplexing programming. + +
+
+ Event Priority + + Signal handler callback functions set via Process::signal + Timer callback functions set via Timer::tick and Timer::after + Deferred execution functions set via Event::defer + Periodic callback functions set via Event::cycle + +
+ +
+ Swoole Event Socket Type + + + + + fd + int + + + + File descriptors, including Swoole\Client->$sock, Swoole\Process->$pipe, or any other file descriptor (fd). + + + + + + stream resource + resource + + + + Resources created by stream_socket_client/fsockopen. + + + + + + socket resource + resource + + + + Resources created by socket_create from the sockets extension require + the --enable-sockets flag during Swoole compilation. + + + + + + object + object + + + + Swoole automatically converts Swoole\Process into UnixSocket and Swoole\Client + into connected client sockets at the underlying level. + + + + + +
+
&reftitle.classsynopsis; diff --git a/reference/swoole/swoole/event/add.xml b/reference/swoole/swoole/event/add.xml index 5764bc189236..65b206edb811 100644 --- a/reference/swoole/swoole/event/add.xml +++ b/reference/swoole/swoole/event/add.xml @@ -1,35 +1,39 @@ - Swoole\Event::add - Add new callback functions of a socket into the EventLoop. + Add a socket to the underlying reactor event listener &reftitle.description; public static boolSwoole\Event::add - intfd + mixedsock callableread_callback callablewrite_callback - stringevents + intflags - + Adds a socket to the underlying reactor event listener. This function can be used in both Server and Client modes. - + + + 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. + + &reftitle.parameters; - fd + sock - + File descriptor, stream resource, sockets resource, or object. @@ -37,7 +41,7 @@ read_callback - + Callback function for readable events. @@ -45,15 +49,16 @@ write_callback - + Callback function for writable events. - events + flags - + Event type mask (e.g. SWOOLE_EVENT_READ, SWOOLE_EVENT_WRITE + or SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE). @@ -63,11 +68,33 @@ &reftitle.returnvalues; - + &return.success; + + &reftitle.examples; + + + <function>Swoole\Event::add</function> example + + +]]> + + + + + + + Swoole\Event::cycle + Define a function to execute at the end of each event loop iteration + + + + &reftitle.description; + + public static boolSwoole\Event::cycle + callablecallback + boolbeforefalse + + + Defines a callback function to execute at the end (or beginning, if before is true) of each event loop iteration. + + + + + &reftitle.parameters; + + + callback + + + The function to execute. Set to null to clear a previously set cycle function. + + + + + before + + + If true, the callback executes before the event loop; if false, after. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + Basic usage + + + + + + + + + diff --git a/reference/swoole/swoole/event/defer.xml b/reference/swoole/swoole/event/defer.xml index 007cd6ed4f89..b3289177d60a 100644 --- a/reference/swoole/swoole/event/defer.xml +++ b/reference/swoole/swoole/event/defer.xml @@ -1,32 +1,30 @@ - Swoole\Event::defer - Add a callback function to the next event loop. + Execute a function at the start of the next event loop &reftitle.description; public static voidSwoole\Event::defer - mixedcallback + callablecallback_function - + Schedules a function to run at the start of the next event loop iteration. - &reftitle.parameters; - callback + callback_function - + Callback function to execute (no parameters allowed; use use for closure variables). @@ -36,11 +34,27 @@ &reftitle.returnvalues; - + No return value. - + + &reftitle.examples; + + + <function>Swoole\Event::defer</function> example + + +]]> + + + + - Swoole\Event::del - Remove all event callback functions of a socket. + Remove a socket from reactor event listener &reftitle.description; public static boolSwoole\Event::del - stringfd + mixedsock - + Removes a socket from the reactor event listener. - + + + Always call Event::del to unregister event monitoring prior to closing the socket. + Failure to do so can result in memory leaks. + + &reftitle.parameters; - fd + sock - + Socket file descriptor to remove. @@ -36,11 +40,9 @@ &reftitle.returnvalues; - + &return.success; - - - - + - Swoole\Event::exit - Exit the eventloop, only available at client side. + Swoole\Event::dispatch + Perform a single event loop iteration &reftitle.description; - public static voidSwoole\Event::exit + public static voidSwoole\Event::dispatch - + 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. - - - - - &reftitle.parameters; - &no.function.parameters; &reftitle.returnvalues; - + No return value. - + + &reftitle.examples; + + + Manual event loop control + + + + + + + + + Swoole\Event::isset + Check if a socket is being monitored in the event loop + + + + &reftitle.description; + + public static boolSwoole\Event::isset + mixedfd + intevents + + SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE + + + + + Checks whether the specified file descriptor is being monitored for the given event types in the event loop. + + + + + &reftitle.parameters; + + + fd + + + File descriptor (stream/socket resource, integer, or object). + + + + + events + + + Event types to check (bitmask of SWOOLE_EVENT_READ and/or SWOOLE_EVENT_WRITE). + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + Checking event monitoring status + + + + + + + + + diff --git a/reference/swoole/swoole/event/set.xml b/reference/swoole/swoole/event/set.xml index a070b16b1f8c..6f50f73108a6 100644 --- a/reference/swoole/swoole/event/set.xml +++ b/reference/swoole/swoole/event/set.xml @@ -1,35 +1,62 @@ - Swoole\Event::set - Update the event callback functions of a socket. + Modify event listener callbacks and mask &reftitle.description; public static boolSwoole\Event::set - intfd - stringread_callback - stringwrite_callback - stringevents + mixedsock + callableread_callback + callablewrite_callback + intflags - + Modifies the event listener callbacks and mask for the given file descriptor. - + + + When $read_callback is not null, the readable event callback function will be modified to the specified function. + + + + + When $write_callback is not null, the writable event callback function will be updated to the specified function. + + + + + Setting SWOOLE_EVENT_READ alone disables write event listening, + while setting SWOOLE_EVENT_WRITE alone disables read event listening. + + + + + Swoole\Event::set replaces callbacks but does not free them. + Specifying null for callbacks (e.g., read_callback/write_callback) + preserves the existing callbacks instead of clearing them. + + + + + Listening for SWOOLE_EVENT_READ without a read_callback (or SWOOLE_EVENT_WRITE without a write_callback) + will cause the operation to fail and return false. + + &reftitle.parameters; - fd + sock - + File descriptor, stream resource, sockets resource, or object. @@ -37,7 +64,7 @@ read_callback - + Callback function for readable events. @@ -45,15 +72,16 @@ write_callback - + Callback function for writable events. - events + flags - + Event type mask (e.g. SWOOLE_EVENT_READ, SWOOLE_EVENT_WRITE + or SWOOLE_EVENT_READ | SWOOLE_EVENT_WRITE). @@ -63,11 +91,9 @@ &reftitle.returnvalues; - + &return.success; - - - Swoole\Event::wait - Description + Start event loop @@ -14,26 +13,36 @@ - + Starts the event loop. Place this at the end of your PHP program. - - &warn.undocumented.func; - - - - - &reftitle.parameters; - &no.function.parameters; &reftitle.returnvalues; - + No return value. + + &reftitle.examples; + + + <function>Swoole\Event::wait</function> example + + +]]> + + + + - Swoole\Event::write - Write data to the socket. + Write data to socket asynchronously &reftitle.description; - public static voidSwoole\Event::write - stringfd - stringdata + public static boolSwoole\Event::write + mixedfd + mixeddata - + Makes data sending asynchronous for stream/sockets resources. - + + + If data is continuously written to a socket but the peer cannot read fast enough, the socket buffer + will eventually fill up. In this case, the Swoole underlying layer will store the excess data + in an in-memory buffer and wait for the writable event to trigger before attempting to write + to the socket again. However, if the in-memory buffer also becomes full, Swoole will throw a + "pipe buffer overflow, reactor will block" error and switch to blocking mode, pausing further + writes until space becomes available. + + + + + The buffer-full return of false is an atomic operation—it guarantees + either complete success (all data written) or total failure (nothing written). + + + + + Event::write cannot be used with SSL/TLS-encrypted streams or sockets (tunneled connections). + + + + + Upon successful execution, Event::write will automatically switch the $socket to non-blocking mode. + + @@ -27,7 +51,7 @@ fd - + File descriptor (stream/socket resource, integer, or object). @@ -35,7 +59,7 @@ data - + Data to send (length must not exceed socket buffer size). @@ -45,11 +69,32 @@ &reftitle.returnvalues; - + &return.success; + + &reftitle.examples; + + + <function>Swoole\Event::write</function> example + + +]]> + + + +