| 1 |
<?php |
| 2 |
|
| 3 |
namespace React\Stream; |
| 4 |
|
| 5 |
use Evenement\EventEmitterInterface; |
| 6 |
|
| 7 |
/** |
| 8 |
* The `ReadableStreamInterface` is responsible for providing an interface for |
| 9 |
* read-only streams and the readable side of duplex streams. |
| 10 |
* |
| 11 |
* Besides defining a few methods, this interface also implements the |
| 12 |
* `EventEmitterInterface` which allows you to react to certain events: |
| 13 |
* |
| 14 |
* data event: |
| 15 |
* The `data` event will be emitted whenever some data was read/received |
| 16 |
* from this source stream. |
| 17 |
* The event receives a single mixed argument for incoming data. |
| 18 |
* |
| 19 |
* ```php |
| 20 |
* $stream->on('data', function ($data) { |
| 21 |
* echo $data; |
| 22 |
* }); |
| 23 |
* ``` |
| 24 |
* |
| 25 |
* This event MAY be emitted any number of times, which may be zero times if |
| 26 |
* this stream does not send any data at all. |
| 27 |
* It SHOULD not be emitted after an `end` or `close` event. |
| 28 |
* |
| 29 |
* The given `$data` argument may be of mixed type, but it's usually |
| 30 |
* recommended it SHOULD be a `string` value or MAY use a type that allows |
| 31 |
* representation as a `string` for maximum compatibility. |
| 32 |
* |
| 33 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 34 |
* will emit the raw (binary) payload data that is received over the wire as |
| 35 |
* chunks of `string` values. |
| 36 |
* |
| 37 |
* Due to the stream-based nature of this, the sender may send any number |
| 38 |
* of chunks with varying sizes. There are no guarantees that these chunks |
| 39 |
* will be received with the exact same framing the sender intended to send. |
| 40 |
* In other words, many lower-level protocols (such as TCP/IP) transfer the |
| 41 |
* data in chunks that may be anywhere between single-byte values to several |
| 42 |
* dozens of kilobytes. You may want to apply a higher-level protocol to |
| 43 |
* these low-level data chunks in order to achieve proper message framing. |
| 44 |
* |
| 45 |
* end event: |
| 46 |
* The `end` event will be emitted once the source stream has successfully |
| 47 |
* reached the end of the stream (EOF). |
| 48 |
* |
| 49 |
* ```php |
| 50 |
* $stream->on('end', function () { |
| 51 |
* echo 'END'; |
| 52 |
* }); |
| 53 |
* ``` |
| 54 |
* |
| 55 |
* This event SHOULD be emitted once or never at all, depending on whether |
| 56 |
* a successful end was detected. |
| 57 |
* It SHOULD NOT be emitted after a previous `end` or `close` event. |
| 58 |
* It MUST NOT be emitted if the stream closes due to a non-successful |
| 59 |
* end, such as after a previous `error` event. |
| 60 |
* |
| 61 |
* After the stream is ended, it MUST switch to non-readable mode, |
| 62 |
* see also `isReadable()`. |
| 63 |
* |
| 64 |
* This event will only be emitted if the *end* was reached successfully, |
| 65 |
* not if the stream was interrupted by an unrecoverable error or explicitly |
| 66 |
* closed. Not all streams know this concept of a "successful end". |
| 67 |
* Many use-cases involve detecting when the stream closes (terminates) |
| 68 |
* instead, in this case you should use the `close` event. |
| 69 |
* After the stream emits an `end` event, it SHOULD usually be followed by a |
| 70 |
* `close` event. |
| 71 |
* |
| 72 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 73 |
* will emit this event if either the remote side closes the connection or |
| 74 |
* a file handle was successfully read until reaching its end (EOF). |
| 75 |
* |
| 76 |
* Note that this event should not be confused with the `end()` method. |
| 77 |
* This event defines a successful end *reading* from a source stream, while |
| 78 |
* the `end()` method defines *writing* a successful end to a destination |
| 79 |
* stream. |
| 80 |
* |
| 81 |
* error event: |
| 82 |
* The `error` event will be emitted once a fatal error occurs, usually while |
| 83 |
* trying to read from this stream. |
| 84 |
* The event receives a single `Exception` argument for the error instance. |
| 85 |
* |
| 86 |
* ```php |
| 87 |
* $stream->on('error', function (Exception $e) { |
| 88 |
* echo 'Error: ' . $e->getMessage() . PHP_EOL; |
| 89 |
* }); |
| 90 |
* ``` |
| 91 |
* |
| 92 |
* This event SHOULD be emitted once the stream detects a fatal error, such |
| 93 |
* as a fatal transmission error or after an unexpected `data` or premature |
| 94 |
* `end` event. |
| 95 |
* It SHOULD NOT be emitted after a previous `error`, `end` or `close` event. |
| 96 |
* It MUST NOT be emitted if this is not a fatal error condition, such as |
| 97 |
* a temporary network issue that did not cause any data to be lost. |
| 98 |
* |
| 99 |
* After the stream errors, it MUST close the stream and SHOULD thus be |
| 100 |
* followed by a `close` event and then switch to non-readable mode, see |
| 101 |
* also `close()` and `isReadable()`. |
| 102 |
* |
| 103 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 104 |
* only deal with data transmission and do not make assumption about data |
| 105 |
* boundaries (such as unexpected `data` or premature `end` events). |
| 106 |
* In other words, many lower-level protocols (such as TCP/IP) may choose |
| 107 |
* to only emit this for a fatal transmission error once and will then |
| 108 |
* close (terminate) the stream in response. |
| 109 |
* |
| 110 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 111 |
* how the writable side of the stream also implements an `error` event. |
| 112 |
* In other words, an error may occur while either reading or writing the |
| 113 |
* stream which should result in the same error processing. |
| 114 |
* |
| 115 |
* close event: |
| 116 |
* The `close` event will be emitted once the stream closes (terminates). |
| 117 |
* |
| 118 |
* ```php |
| 119 |
* $stream->on('close', function () { |
| 120 |
* echo 'CLOSED'; |
| 121 |
* }); |
| 122 |
* ``` |
| 123 |
* |
| 124 |
* This event SHOULD be emitted once or never at all, depending on whether |
| 125 |
* the stream ever terminates. |
| 126 |
* It SHOULD NOT be emitted after a previous `close` event. |
| 127 |
* |
| 128 |
* After the stream is closed, it MUST switch to non-readable mode, |
| 129 |
* see also `isReadable()`. |
| 130 |
* |
| 131 |
* Unlike the `end` event, this event SHOULD be emitted whenever the stream |
| 132 |
* closes, irrespective of whether this happens implicitly due to an |
| 133 |
* unrecoverable error or explicitly when either side closes the stream. |
| 134 |
* If you only want to detect a *successful* end, you should use the `end` |
| 135 |
* event instead. |
| 136 |
* |
| 137 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 138 |
* will likely choose to emit this event after reading a *successful* `end` |
| 139 |
* event or after a fatal transmission `error` event. |
| 140 |
* |
| 141 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 142 |
* how the writable side of the stream also implements a `close` event. |
| 143 |
* In other words, after receiving this event, the stream MUST switch into |
| 144 |
* non-writable AND non-readable mode, see also `isWritable()`. |
| 145 |
* Note that this event should not be confused with the `end` event. |
| 146 |
* |
| 147 |
* The event callback functions MUST be a valid `callable` that obeys strict |
| 148 |
* parameter definitions and MUST accept event parameters exactly as documented. |
| 149 |
* The event callback functions MUST NOT throw an `Exception`. |
| 150 |
* The return value of the event callback functions will be ignored and has no |
| 151 |
* effect, so for performance reasons you're recommended to not return any |
| 152 |
* excessive data structures. |
| 153 |
* |
| 154 |
* Every implementation of this interface MUST follow these event semantics in |
| 155 |
* order to be considered a well-behaving stream. |
| 156 |
* |
| 157 |
* > Note that higher-level implementations of this interface may choose to |
| 158 |
* define additional events with dedicated semantics not defined as part of |
| 159 |
* this low-level stream specification. Conformance with these event semantics |
| 160 |
* is out of scope for this interface, so you may also have to refer to the |
| 161 |
* documentation of such a higher-level implementation. |
| 162 |
* |
| 163 |
* @see EventEmitterInterface |
| 164 |
*/ |
| 165 |
interface ReadableStreamInterface extends EventEmitterInterface |
| 166 |
{ |
| 167 |
/** |
| 168 |
* Checks whether this stream is in a readable state (not closed already). |
| 169 |
* |
| 170 |
* This method can be used to check if the stream still accepts incoming |
| 171 |
* data events or if it is ended or closed already. |
| 172 |
* Once the stream is non-readable, no further `data` or `end` events SHOULD |
| 173 |
* be emitted. |
| 174 |
* |
| 175 |
* ```php |
| 176 |
* assert($stream->isReadable() === false); |
| 177 |
* |
| 178 |
* $stream->on('data', assertNeverCalled()); |
| 179 |
* $stream->on('end', assertNeverCalled()); |
| 180 |
* ``` |
| 181 |
* |
| 182 |
* A successfully opened stream always MUST start in readable mode. |
| 183 |
* |
| 184 |
* Once the stream ends or closes, it MUST switch to non-readable mode. |
| 185 |
* This can happen any time, explicitly through `close()` or |
| 186 |
* implicitly due to a remote close or an unrecoverable transmission error. |
| 187 |
* Once a stream has switched to non-readable mode, it MUST NOT transition |
| 188 |
* back to readable mode. |
| 189 |
* |
| 190 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 191 |
* how the writable side of the stream also implements an `isWritable()` |
| 192 |
* method. Unless this is a half-open duplex stream, they SHOULD usually |
| 193 |
* have the same return value. |
| 194 |
* |
| 195 |
* @return bool |
| 196 |
*/ |
| 197 |
public function isReadable(); |
| 198 |
|
| 199 |
/** |
| 200 |
* Pauses reading incoming data events. |
| 201 |
* |
| 202 |
* Removes the data source file descriptor from the event loop. This |
| 203 |
* allows you to throttle incoming data. |
| 204 |
* |
| 205 |
* Unless otherwise noted, a successfully opened stream SHOULD NOT start |
| 206 |
* in paused state. |
| 207 |
* |
| 208 |
* Once the stream is paused, no futher `data` or `end` events SHOULD |
| 209 |
* be emitted. |
| 210 |
* |
| 211 |
* ```php |
| 212 |
* $stream->pause(); |
| 213 |
* |
| 214 |
* $stream->on('data', assertShouldNeverCalled()); |
| 215 |
* $stream->on('end', assertShouldNeverCalled()); |
| 216 |
* ``` |
| 217 |
* |
| 218 |
* This method is advisory-only, though generally not recommended, the |
| 219 |
* stream MAY continue emitting `data` events. |
| 220 |
* |
| 221 |
* You can continue processing events by calling `resume()` again. |
| 222 |
* |
| 223 |
* Note that both methods can be called any number of times, in particular |
| 224 |
* calling `pause()` more than once SHOULD NOT have any effect. |
| 225 |
* |
| 226 |
* @see self::resume() |
| 227 |
* @return void |
| 228 |
*/ |
| 229 |
public function pause(); |
| 230 |
|
| 231 |
/** |
| 232 |
* Resumes reading incoming data events. |
| 233 |
* |
| 234 |
* Re-attach the data source after a previous `pause()`. |
| 235 |
* |
| 236 |
* ```php |
| 237 |
* $stream->pause(); |
| 238 |
* |
| 239 |
* Loop::addTimer(1.0, function () use ($stream) { |
| 240 |
* $stream->resume(); |
| 241 |
* }); |
| 242 |
* ``` |
| 243 |
* |
| 244 |
* Note that both methods can be called any number of times, in particular |
| 245 |
* calling `resume()` without a prior `pause()` SHOULD NOT have any effect. |
| 246 |
* |
| 247 |
* @see self::pause() |
| 248 |
* @return void |
| 249 |
*/ |
| 250 |
public function resume(); |
| 251 |
|
| 252 |
/** |
| 253 |
* Pipes all the data from this readable source into the given writable destination. |
| 254 |
* |
| 255 |
* Automatically sends all incoming data to the destination. |
| 256 |
* Automatically throttles the source based on what the destination can handle. |
| 257 |
* |
| 258 |
* ```php |
| 259 |
* $source->pipe($dest); |
| 260 |
* ``` |
| 261 |
* |
| 262 |
* Similarly, you can also pipe an instance implementing `DuplexStreamInterface` |
| 263 |
* into itself in order to write back all the data that is received. |
| 264 |
* This may be a useful feature for a TCP/IP echo service: |
| 265 |
* |
| 266 |
* ```php |
| 267 |
* $connection->pipe($connection); |
| 268 |
* ``` |
| 269 |
* |
| 270 |
* This method returns the destination stream as-is, which can be used to |
| 271 |
* set up chains of piped streams: |
| 272 |
* |
| 273 |
* ```php |
| 274 |
* $source->pipe($decodeGzip)->pipe($filterBadWords)->pipe($dest); |
| 275 |
* ``` |
| 276 |
* |
| 277 |
* By default, this will call `end()` on the destination stream once the |
| 278 |
* source stream emits an `end` event. This can be disabled like this: |
| 279 |
* |
| 280 |
* ```php |
| 281 |
* $source->pipe($dest, array('end' => false)); |
| 282 |
* ``` |
| 283 |
* |
| 284 |
* Note that this only applies to the `end` event. |
| 285 |
* If an `error` or explicit `close` event happens on the source stream, |
| 286 |
* you'll have to manually close the destination stream: |
| 287 |
* |
| 288 |
* ```php |
| 289 |
* $source->pipe($dest); |
| 290 |
* $source->on('close', function () use ($dest) { |
| 291 |
* $dest->end('BYE!'); |
| 292 |
* }); |
| 293 |
* ``` |
| 294 |
* |
| 295 |
* If the source stream is not readable (closed state), then this is a NO-OP. |
| 296 |
* |
| 297 |
* ```php |
| 298 |
* $source->close(); |
| 299 |
* $source->pipe($dest); // NO-OP |
| 300 |
* ``` |
| 301 |
* |
| 302 |
* If the destinantion stream is not writable (closed state), then this will simply |
| 303 |
* throttle (pause) the source stream: |
| 304 |
* |
| 305 |
* ```php |
| 306 |
* $dest->close(); |
| 307 |
* $source->pipe($dest); // calls $source->pause() |
| 308 |
* ``` |
| 309 |
* |
| 310 |
* Similarly, if the destination stream is closed while the pipe is still |
| 311 |
* active, it will also throttle (pause) the source stream: |
| 312 |
* |
| 313 |
* ```php |
| 314 |
* $source->pipe($dest); |
| 315 |
* $dest->close(); // calls $source->pause() |
| 316 |
* ``` |
| 317 |
* |
| 318 |
* Once the pipe is set up successfully, the destination stream MUST emit |
| 319 |
* a `pipe` event with this source stream an event argument. |
| 320 |
* |
| 321 |
* @param WritableStreamInterface $dest |
| 322 |
* @param array $options |
| 323 |
* @return WritableStreamInterface $dest stream as-is |
| 324 |
*/ |
| 325 |
public function pipe(WritableStreamInterface $dest, array $options = array()); |
| 326 |
|
| 327 |
/** |
| 328 |
* Closes the stream (forcefully). |
| 329 |
* |
| 330 |
* This method can be used to (forcefully) close the stream. |
| 331 |
* |
| 332 |
* ```php |
| 333 |
* $stream->close(); |
| 334 |
* ``` |
| 335 |
* |
| 336 |
* Once the stream is closed, it SHOULD emit a `close` event. |
| 337 |
* Note that this event SHOULD NOT be emitted more than once, in particular |
| 338 |
* if this method is called multiple times. |
| 339 |
* |
| 340 |
* After calling this method, the stream MUST switch into a non-readable |
| 341 |
* mode, see also `isReadable()`. |
| 342 |
* This means that no further `data` or `end` events SHOULD be emitted. |
| 343 |
* |
| 344 |
* ```php |
| 345 |
* $stream->close(); |
| 346 |
* assert($stream->isReadable() === false); |
| 347 |
* |
| 348 |
* $stream->on('data', assertNeverCalled()); |
| 349 |
* $stream->on('end', assertNeverCalled()); |
| 350 |
* ``` |
| 351 |
* |
| 352 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 353 |
* how the writable side of the stream also implements a `close()` method. |
| 354 |
* In other words, after calling this method, the stream MUST switch into |
| 355 |
* non-writable AND non-readable mode, see also `isWritable()`. |
| 356 |
* Note that this method should not be confused with the `end()` method. |
| 357 |
* |
| 358 |
* @return void |
| 359 |
* @see WritableStreamInterface::close() |
| 360 |
*/ |
| 361 |
public function close(); |
| 362 |
} |