Skip to content
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

[WIP] Change many SHOULDs to MUSTs to ensure clear behavior #104

Closed
wants to merge 1 commit into from
Closed

[WIP] Change many SHOULDs to MUSTs to ensure clear behavior #104

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
45 changes: 23 additions & 22 deletions src/ReadableStreamInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
*
* This event MAY be emitted any number of times, which may be zero times if
* this stream does not send any data at all.
* It SHOULD not be emitted after an `end` or `close` event.
* It MUST not be emitted after an `end` or `close` event.
*
* The given `$data` argument may be of mixed type, but it's usually
* recommended it SHOULD be a `string` value or MAY use a type that allows
Expand All @@ -43,7 +43,7 @@
* these low-level data chunks in order to achieve proper message framing.
*
* end event:
* The `end` event will be emitted once the source stream has successfully
* The `end` event MUST be emitted once the source stream has successfully
* reached the end of the stream (EOF).
*
* ```php
Expand All @@ -52,21 +52,21 @@
* });
* ```
*
* This event SHOULD be emitted once or never at all, depending on whether
* This event MUST be emitted once or never at all, depending on whether
* a successful end was detected.
* It SHOULD NOT be emitted after a previous `end` or `close` event.
* It MUST NOT be emitted after a previous `end` or `close` event.
* It MUST NOT be emitted if the stream closes due to a non-successful
* end, such as after a previous `error` event.
*
* After the stream is ended, it MUST switch to non-readable mode,
* After the stream has ended, it MUST switch to non-readable mode,
* see also `isReadable()`.
*
* This event will only be emitted if the *end* was reached successfully,
* not if the stream was interrupted by an unrecoverable error or explicitly
* closed. Not all streams know this concept of a "successful end".
* Many use-cases involve detecting when the stream closes (terminates)
* instead, in this case you should use the `close` event.
* After the stream emits an `end` event, it SHOULD usually be followed by a
* After the stream emits an `end` event, it MUST be followed by a
* `close` event.
*
* Many common streams (such as a TCP/IP connection or a file-based stream)
Expand All @@ -79,24 +79,25 @@
* stream.
*
* error event:
* The `error` event will be emitted once a fatal error occurs, usually while
* The `error` event MUST be emitted once a fatal error occurs, usually while
* trying to read from this stream.
* The event receives a single `Exception` argument for the error instance.
* The event receives a single `Throwable` / `Exception` argument for the error
* instance.
*
* ```php
* $stream->on('error', function (Exception $e) {
* $stream->on('error', function ($e) {
* echo 'Error: ' . $e->getMessage() . PHP_EOL;
* });
* ```
*
* This event SHOULD be emitted once the stream detects a fatal error, such
* This event MUST be emitted once the stream detects a fatal error, such
* as a fatal transmission error or after an unexpected `data` or premature
* `end` event.
* It SHOULD NOT be emitted after a previous `error`, `end` or `close` event.
* It MUST NOT be emitted after a previous `error`, `end` or `close` event.
* It MUST NOT be emitted if this is not a fatal error condition, such as
* a temporary network issue that did not cause any data to be lost.
*
* After the stream errors, it MUST close the stream and SHOULD thus be
* After the stream errors, it MUST close the stream and MUST thus be
* followed by a `close` event and then switch to non-readable mode, see
* also `close()` and `isReadable()`.
*
Expand All @@ -113,22 +114,22 @@
* stream which should result in the same error processing.
*
* close event:
* The `close` event will be emitted once the stream closes (terminates).
* The `close` event MUST be emitted once the stream closes (terminates).
*
* ```php
* $stream->on('close', function () {
* echo 'CLOSED';
* });
* ```
*
* This event SHOULD be emitted once or never at all, depending on whether
* This event MUST be emitted once or never at all, depending on whether
* the stream ever terminates.
* It SHOULD NOT be emitted after a previous `close` event.
* It MUST NOT be emitted after a previous `close` event.
*
* After the stream is closed, it MUST switch to non-readable mode,
* see also `isReadable()`.
*
* Unlike the `end` event, this event SHOULD be emitted whenever the stream
* Unlike the `end` event, this event MUST be emitted whenever the stream
* closes, irrespective of whether this happens implicitly due to an
* unrecoverable error or explicitly when either side closes the stream.
* If you only want to detect a *successful* end, you should use the `end`
Expand All @@ -146,7 +147,7 @@
*
* The event callback functions MUST be a valid `callable` that obeys strict
* parameter definitions and MUST accept event parameters exactly as documented.
* The event callback functions MUST NOT throw an `Exception`.
* The event callback functions MUST NOT throw an `Exception` / `Throwable`.
* The return value of the event callback functions will be ignored and has no
* effect, so for performance reasons you're recommended to not return any
* excessive data structures.
Expand All @@ -169,7 +170,7 @@ interface ReadableStreamInterface extends EventEmitterInterface
*
* This method can be used to check if the stream still accepts incoming
* data events or if it is ended or closed already.
* Once the stream is non-readable, no further `data` or `end` events SHOULD
* Once the stream is non-readable, no further `data` or `end` events MUST
* be emitted.
*
* ```php
Expand All @@ -189,7 +190,7 @@ interface ReadableStreamInterface extends EventEmitterInterface
*
* If this stream is a `DuplexStreamInterface`, you should also notice
* how the writable side of the stream also implements an `isWritable()`
* method. Unless this is a half-open duplex stream, they SHOULD usually
* method. Unless this is a half-open duplex stream, they will usually
* have the same return value.
*
* @return bool
Expand Down Expand Up @@ -333,13 +334,13 @@ public function pipe(WritableStreamInterface $dest, array $options = array());
* $stream->close();
* ```
*
* Once the stream is closed, it SHOULD emit a `close` event.
* Note that this event SHOULD NOT be emitted more than once, in particular
* Once the stream is closed, it MUST emit a `close` event.
* Note that this event MUST NOT be emitted more than once, in particular
* if this method is called multiple times.
*
* After calling this method, the stream MUST switch into a non-readable
* mode, see also `isReadable()`.
* This means that no further `data` or `end` events SHOULD be emitted.
* This means that no further `data` or `end` events MUST be emitted.
*
* ```php
* $stream->close();
Expand Down
53 changes: 27 additions & 26 deletions src/WritableStreamInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
* `EventEmitterInterface` which allows you to react to certain events:
*
* drain event:
* The `drain` event will be emitted whenever the write buffer became full
* The `drain` event MUST be emitted whenever the write buffer became full
* previously and is now ready to accept more data.
*
* ```php
Expand All @@ -31,7 +31,7 @@
* This event is mostly used internally, see also `write()` for more details.
*
* pipe event:
* The `pipe` event will be emitted whenever a readable stream is `pipe()`d
* The `pipe` event MUST be emitted whenever a readable stream is `pipe()`d
* into this stream.
* The event receives a single `ReadableStreamInterface` argument for the
* source stream.
Expand Down Expand Up @@ -59,23 +59,24 @@
* This event is mostly used internally, see also `pipe()` for more details.
*
* error event:
* The `error` event will be emitted once a fatal error occurs, usually while
* The `error` event MUST be emitted once a fatal error occurs, usually while
* trying to write to this stream.
* The event receives a single `Exception` argument for the error instance.
* The event receives a single `Throwable` / `Exception` argument for the error
* instance.
*
* ```php
* $stream->on('error', function (Exception $e) {
* $stream->on('error', function ($e) {
* echo 'Error: ' . $e->getMessage() . PHP_EOL;
* });
* ```
*
* This event SHOULD be emitted once the stream detects a fatal error, such
* This event MUST be emitted once the stream detects a fatal error, such
* as a fatal transmission error.
* It SHOULD NOT be emitted after a previous `error` or `close` event.
* It MUST NOT be emitted after a previous `error` or `close` event.
* It MUST NOT be emitted if this is not a fatal error condition, such as
* a temporary network issue that did not cause any data to be lost.
*
* After the stream errors, it MUST close the stream and SHOULD thus be
* After the stream errors, it MUST close the stream and MUST thus be
* followed by a `close` event and then switch to non-writable mode, see
* also `close()` and `isWritable()`.
*
Expand All @@ -90,22 +91,22 @@
* stream which should result in the same error processing.
*
* close event:
* The `close` event will be emitted once the stream closes (terminates).
* The `close` event MUST be emitted once the stream closes (terminates).
*
* ```php
* $stream->on('close', function () {
* echo 'CLOSED';
* });
* ```
*
* This event SHOULD be emitted once or never at all, depending on whether
* This event MUST be emitted once or never at all, depending on whether
* the stream ever terminates.
* It SHOULD NOT be emitted after a previous `close` event.
* It MUST NOT be emitted after a previous `close` event.
*
* After the stream is closed, it MUST switch to non-writable mode,
* see also `isWritable()`.
*
* This event SHOULD be emitted whenever the stream closes, irrespective of
* This event MUST be emitted whenever the stream closes, irrespective of
* whether this happens implicitly due to an unrecoverable error or
* explicitly when either side closes the stream.
*
Expand Down Expand Up @@ -184,25 +185,25 @@ public function isWritable();
*
* Many common streams (such as a TCP/IP connection or file-based stream)
* may choose to buffer all given data and schedule a future flush by using
* an underlying EventLoop to check when the resource is actually writable.
* an underlying event loop to check when the resource is actually writable.
*
* If a stream cannot handle writing (or flushing) the data, it SHOULD emit
* an `error` event and MAY `close()` the stream if it can not recover from
* If a stream cannot handle writing (or flushing) the data, it MUST emit
* an `error` event and MUST `close()` the stream if it can not recover from
* this error.
*
* If the internal buffer is full after adding `$data`, then `write()`
* SHOULD return `false`, indicating that the caller should stop sending
* MUST return `false`, indicating that the caller should stop sending
* data until the buffer drains.
* The stream SHOULD send a `drain` event once the buffer is ready to accept
* The stream MUST send a `drain` event once the buffer is ready to accept
* more data.
*
* Similarly, if the the stream is not writable (already in a closed state)
* it MUST NOT process the given `$data` and SHOULD return `false`,
* it MUST NOT process the given `$data` and MUST return `false`,
* indicating that the caller should stop sending data.
*
* The given `$data` argument MAY be of mixed type, but it's usually
* recommended it SHOULD be a `string` value or MAY use a type that allows
* representation as a `string` for maximum compatibility.
* The given `$data` argument MAY be of mixed type, but it's RECOMMENDED
* to be a `string` value or a type that allows representation as a
* `string` for maximum compatibility.
*
* Many common streams (such as a TCP/IP connection or a file-based stream)
* will only accept the raw (binary) payload data that is transferred over
Expand Down Expand Up @@ -237,9 +238,9 @@ public function write($data);
* this method MAY `close()` the stream immediately.
*
* If there's still data in the buffer that needs to be flushed first, then
* this method SHOULD try to write out this data and only then `close()`
* this method MUST try to write out this data and only then `close()`
* the stream.
* Once the stream is closed, it SHOULD emit a `close` event.
* Once the stream is closed, it MUST emit a `close` event.
*
* Note that this interface gives you no control over explicitly flushing
* the buffered data, as finding the appropriate time for this is beyond the
Expand All @@ -248,7 +249,7 @@ public function write($data);
*
* Many common streams (such as a TCP/IP connection or file-based stream)
* may choose to buffer all given data and schedule a future flush by using
* an underlying EventLoop to check when the resource is actually writable.
* an underlying event loop to check when the resource is actually writable.
*
* You can optionally pass some final data that is written to the stream
* before ending the stream. If a non-`null` value is given as `$data`, then
Expand Down Expand Up @@ -305,8 +306,8 @@ public function end($data = null);
* $stream->close();
* ```
*
* Once the stream is closed, it SHOULD emit a `close` event.
* Note that this event SHOULD NOT be emitted more than once, in particular
* Once the stream is closed, it MUST emit a `close` event.
* Note that this event MUST NOT be emitted more than once, in particular
* if this method is called multiple times.
*
* After calling this method, the stream MUST switch into a non-writable
Expand Down