From 536aef8fb79012b0d4713bb8818cbfcfe0569a2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Mon, 4 Dec 2017 11:59:32 +0100 Subject: [PATCH] Documentation for edge-triggered event listeners and stream buffers --- README.md | 17 +++++++++++++++++ src/ExtLibeventLoop.php | 9 +++++++++ src/LoopInterface.php | 8 ++++++++ 3 files changed, 34 insertions(+) diff --git a/README.md b/README.md index 27bb0bd3..2c48b410 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,15 @@ To reiterate: Using this event loop on PHP 7 is not recommended. Accordingly, the [`Factory`](#factory) will not try to use this event loop on PHP 7. +This event loop is known to trigger a readable listener only if +the stream *becomes* readable (edge-triggered) and may not trigger if the +stream has already been readable from the beginning. +This also implies that a stream may not be recognized as readable when data +is still left in PHP's internal stream buffers. +As such, it's recommended to use `stream_set_read_buffer($stream, 0);` +to disable PHP's internal read buffer in this case. +See also [`addReadStream()`](#addreadstream) for more details. + #### ExtLibevLoop An `ext-libev` based event loop. @@ -482,6 +491,14 @@ read event listener for this stream. The execution order of listeners when multiple streams become ready at the same time is not guaranteed. +Some event loop implementations are known to only trigger the listener if +the stream *becomes* readable (edge-triggered) and may not trigger if the +stream has already been readable from the beginning. +This also implies that a stream may not be recognized as readable when data +is still left in PHP's internal stream buffers. +As such, it's recommended to use `stream_set_read_buffer($stream, 0);` +to disable PHP's internal read buffer in this case. + #### addWriteStream() > Advanced! Note that this low-level API is considered advanced usage. diff --git a/src/ExtLibeventLoop.php b/src/ExtLibeventLoop.php index 0d0a1b3e..08896b4f 100644 --- a/src/ExtLibeventLoop.php +++ b/src/ExtLibeventLoop.php @@ -22,6 +22,15 @@ * Accordingly, the [`Factory`](#factory) will not try to use this event loop on * PHP 7. * + * This event loop is known to trigger a readable listener only if + * the stream *becomes* readable (edge-triggered) and may not trigger if the + * stream has already been readable from the beginning. + * This also implies that a stream may not be recognized as readable when data + * is still left in PHP's internal stream buffers. + * As such, it's recommended to use `stream_set_read_buffer($stream, 0);` + * to disable PHP's internal read buffer in this case. + * See also [`addReadStream()`](#addreadstream) for more details. + * * @link https://pecl.php.net/package/libevent */ class ExtLibeventLoop implements LoopInterface diff --git a/src/LoopInterface.php b/src/LoopInterface.php index 57783fab..fa905914 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -94,6 +94,14 @@ public function addReadStream($stream, callable $listener); * The execution order of listeners when multiple streams become ready at * the same time is not guaranteed. * + * Some event loop implementations are known to only trigger the listener if + * the stream *becomes* readable (edge-triggered) and may not trigger if the + * stream has already been readable from the beginning. + * This also implies that a stream may not be recognized as readable when data + * is still left in PHP's internal stream buffers. + * As such, it's recommended to use `stream_set_read_buffer($stream, 0);` + * to disable PHP's internal read buffer in this case. + * * @param resource $stream The PHP stream resource to check. * @param callable $listener Invoked when the stream is ready. * @see self::removeWriteStream()