Merge pull request #129 from clue-labs/edge-triggered

Documentation for edge-triggered event listeners and stream buffers

Author: jsor

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.

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

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