| 1 |
<?php |
| 2 |
|
| 3 |
namespace React\Stream; |
| 4 |
|
| 5 |
use Evenement\EventEmitterInterface; |
| 6 |
|
| 7 |
/** |
| 8 |
* The `WritableStreamInterface` is responsible for providing an interface for |
| 9 |
* write-only streams and the writable 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 |
* drain event: |
| 15 |
* The `drain` event will be emitted whenever the write buffer became full |
| 16 |
* previously and is now ready to accept more data. |
| 17 |
* |
| 18 |
* ```php |
| 19 |
* $stream->on('drain', function () use ($stream) { |
| 20 |
* echo 'Stream is now ready to accept more data'; |
| 21 |
* }); |
| 22 |
* ``` |
| 23 |
* |
| 24 |
* This event SHOULD be emitted once every time the buffer became full |
| 25 |
* previously and is now ready to accept more data. |
| 26 |
* In other words, this event MAY be emitted any number of times, which may |
| 27 |
* be zero times if the buffer never became full in the first place. |
| 28 |
* This event SHOULD NOT be emitted if the buffer has not become full |
| 29 |
* previously. |
| 30 |
* |
| 31 |
* This event is mostly used internally, see also `write()` for more details. |
| 32 |
* |
| 33 |
* pipe event: |
| 34 |
* The `pipe` event will be emitted whenever a readable stream is `pipe()`d |
| 35 |
* into this stream. |
| 36 |
* The event receives a single `ReadableStreamInterface` argument for the |
| 37 |
* source stream. |
| 38 |
* |
| 39 |
* ```php |
| 40 |
* $stream->on('pipe', function (ReadableStreamInterface $source) use ($stream) { |
| 41 |
* echo 'Now receiving piped data'; |
| 42 |
* |
| 43 |
* // explicitly close target if source emits an error |
| 44 |
* $source->on('error', function () use ($stream) { |
| 45 |
* $stream->close(); |
| 46 |
* }); |
| 47 |
* }); |
| 48 |
* |
| 49 |
* $source->pipe($stream); |
| 50 |
* ``` |
| 51 |
* |
| 52 |
* This event MUST be emitted once for each readable stream that is |
| 53 |
* successfully piped into this destination stream. |
| 54 |
* In other words, this event MAY be emitted any number of times, which may |
| 55 |
* be zero times if no stream is ever piped into this stream. |
| 56 |
* This event MUST NOT be emitted if either the source is not readable |
| 57 |
* (closed already) or this destination is not writable (closed already). |
| 58 |
* |
| 59 |
* This event is mostly used internally, see also `pipe()` for more details. |
| 60 |
* |
| 61 |
* error event: |
| 62 |
* The `error` event will be emitted once a fatal error occurs, usually while |
| 63 |
* trying to write to this stream. |
| 64 |
* The event receives a single `Exception` argument for the error instance. |
| 65 |
* |
| 66 |
* ```php |
| 67 |
* $stream->on('error', function (Exception $e) { |
| 68 |
* echo 'Error: ' . $e->getMessage() . PHP_EOL; |
| 69 |
* }); |
| 70 |
* ``` |
| 71 |
* |
| 72 |
* This event SHOULD be emitted once the stream detects a fatal error, such |
| 73 |
* as a fatal transmission error. |
| 74 |
* It SHOULD NOT be emitted after a previous `error` or `close` event. |
| 75 |
* It MUST NOT be emitted if this is not a fatal error condition, such as |
| 76 |
* a temporary network issue that did not cause any data to be lost. |
| 77 |
* |
| 78 |
* After the stream errors, it MUST close the stream and SHOULD thus be |
| 79 |
* followed by a `close` event and then switch to non-writable mode, see |
| 80 |
* also `close()` and `isWritable()`. |
| 81 |
* |
| 82 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 83 |
* only deal with data transmission and may choose |
| 84 |
* to only emit this for a fatal transmission error once and will then |
| 85 |
* close (terminate) the stream in response. |
| 86 |
* |
| 87 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 88 |
* how the readable side of the stream also implements an `error` event. |
| 89 |
* In other words, an error may occur while either reading or writing the |
| 90 |
* stream which should result in the same error processing. |
| 91 |
* |
| 92 |
* close event: |
| 93 |
* The `close` event will be emitted once the stream closes (terminates). |
| 94 |
* |
| 95 |
* ```php |
| 96 |
* $stream->on('close', function () { |
| 97 |
* echo 'CLOSED'; |
| 98 |
* }); |
| 99 |
* ``` |
| 100 |
* |
| 101 |
* This event SHOULD be emitted once or never at all, depending on whether |
| 102 |
* the stream ever terminates. |
| 103 |
* It SHOULD NOT be emitted after a previous `close` event. |
| 104 |
* |
| 105 |
* After the stream is closed, it MUST switch to non-writable mode, |
| 106 |
* see also `isWritable()`. |
| 107 |
* |
| 108 |
* This event SHOULD be emitted whenever the stream closes, irrespective of |
| 109 |
* whether this happens implicitly due to an unrecoverable error or |
| 110 |
* explicitly when either side closes the stream. |
| 111 |
* |
| 112 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 113 |
* will likely choose to emit this event after flushing the buffer from |
| 114 |
* the `end()` method, after receiving a *successful* `end` event or after |
| 115 |
* a fatal transmission `error` event. |
| 116 |
* |
| 117 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 118 |
* how the readable side of the stream also implements a `close` event. |
| 119 |
* In other words, after receiving this event, the stream MUST switch into |
| 120 |
* non-writable AND non-readable mode, see also `isReadable()`. |
| 121 |
* Note that this event should not be confused with the `end` event. |
| 122 |
* |
| 123 |
* The event callback functions MUST be a valid `callable` that obeys strict |
| 124 |
* parameter definitions and MUST accept event parameters exactly as documented. |
| 125 |
* The event callback functions MUST NOT throw an `Exception`. |
| 126 |
* The return value of the event callback functions will be ignored and has no |
| 127 |
* effect, so for performance reasons you're recommended to not return any |
| 128 |
* excessive data structures. |
| 129 |
* |
| 130 |
* Every implementation of this interface MUST follow these event semantics in |
| 131 |
* order to be considered a well-behaving stream. |
| 132 |
* |
| 133 |
* > Note that higher-level implementations of this interface may choose to |
| 134 |
* define additional events with dedicated semantics not defined as part of |
| 135 |
* this low-level stream specification. Conformance with these event semantics |
| 136 |
* is out of scope for this interface, so you may also have to refer to the |
| 137 |
* documentation of such a higher-level implementation. |
| 138 |
* |
| 139 |
* @see EventEmitterInterface |
| 140 |
* @see DuplexStreamInterface |
| 141 |
*/ |
| 142 |
interface WritableStreamInterface extends EventEmitterInterface |
| 143 |
{ |
| 144 |
/** |
| 145 |
* Checks whether this stream is in a writable state (not closed already). |
| 146 |
* |
| 147 |
* This method can be used to check if the stream still accepts writing |
| 148 |
* any data or if it is ended or closed already. |
| 149 |
* Writing any data to a non-writable stream is a NO-OP: |
| 150 |
* |
| 151 |
* ```php |
| 152 |
* assert($stream->isWritable() === false); |
| 153 |
* |
| 154 |
* $stream->write('end'); // NO-OP |
| 155 |
* $stream->end('end'); // NO-OP |
| 156 |
* ``` |
| 157 |
* |
| 158 |
* A successfully opened stream always MUST start in writable mode. |
| 159 |
* |
| 160 |
* Once the stream ends or closes, it MUST switch to non-writable mode. |
| 161 |
* This can happen any time, explicitly through `end()` or `close()` or |
| 162 |
* implicitly due to a remote close or an unrecoverable transmission error. |
| 163 |
* Once a stream has switched to non-writable mode, it MUST NOT transition |
| 164 |
* back to writable mode. |
| 165 |
* |
| 166 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 167 |
* how the readable side of the stream also implements an `isReadable()` |
| 168 |
* method. Unless this is a half-open duplex stream, they SHOULD usually |
| 169 |
* have the same return value. |
| 170 |
* |
| 171 |
* @return bool |
| 172 |
*/ |
| 173 |
public function isWritable(); |
| 174 |
|
| 175 |
/** |
| 176 |
* Write some data into the stream. |
| 177 |
* |
| 178 |
* A successful write MUST be confirmed with a boolean `true`, which means |
| 179 |
* that either the data was written (flushed) immediately or is buffered and |
| 180 |
* scheduled for a future write. Note that this interface gives you no |
| 181 |
* control over explicitly flushing the buffered data, as finding the |
| 182 |
* appropriate time for this is beyond the scope of this interface and left |
| 183 |
* up to the implementation of this interface. |
| 184 |
* |
| 185 |
* Many common streams (such as a TCP/IP connection or file-based stream) |
| 186 |
* may choose to buffer all given data and schedule a future flush by using |
| 187 |
* an underlying EventLoop to check when the resource is actually writable. |
| 188 |
* |
| 189 |
* If a stream cannot handle writing (or flushing) the data, it SHOULD emit |
| 190 |
* an `error` event and MAY `close()` the stream if it can not recover from |
| 191 |
* this error. |
| 192 |
* |
| 193 |
* If the internal buffer is full after adding `$data`, then `write()` |
| 194 |
* SHOULD return `false`, indicating that the caller should stop sending |
| 195 |
* data until the buffer drains. |
| 196 |
* The stream SHOULD send a `drain` event once the buffer is ready to accept |
| 197 |
* more data. |
| 198 |
* |
| 199 |
* Similarly, if the stream is not writable (already in a closed state) |
| 200 |
* it MUST NOT process the given `$data` and SHOULD return `false`, |
| 201 |
* indicating that the caller should stop sending data. |
| 202 |
* |
| 203 |
* The given `$data` argument MAY be of mixed type, but it's usually |
| 204 |
* recommended it SHOULD be a `string` value or MAY use a type that allows |
| 205 |
* representation as a `string` for maximum compatibility. |
| 206 |
* |
| 207 |
* Many common streams (such as a TCP/IP connection or a file-based stream) |
| 208 |
* will only accept the raw (binary) payload data that is transferred over |
| 209 |
* the wire as chunks of `string` values. |
| 210 |
* |
| 211 |
* Due to the stream-based nature of this, the sender may send any number |
| 212 |
* of chunks with varying sizes. There are no guarantees that these chunks |
| 213 |
* will be received with the exact same framing the sender intended to send. |
| 214 |
* In other words, many lower-level protocols (such as TCP/IP) transfer the |
| 215 |
* data in chunks that may be anywhere between single-byte values to several |
| 216 |
* dozens of kilobytes. You may want to apply a higher-level protocol to |
| 217 |
* these low-level data chunks in order to achieve proper message framing. |
| 218 |
* |
| 219 |
* @param mixed|string $data |
| 220 |
* @return bool |
| 221 |
*/ |
| 222 |
public function write($data); |
| 223 |
|
| 224 |
/** |
| 225 |
* Successfully ends the stream (after optionally sending some final data). |
| 226 |
* |
| 227 |
* This method can be used to successfully end the stream, i.e. close |
| 228 |
* the stream after sending out all data that is currently buffered. |
| 229 |
* |
| 230 |
* ```php |
| 231 |
* $stream->write('hello'); |
| 232 |
* $stream->write('world'); |
| 233 |
* $stream->end(); |
| 234 |
* ``` |
| 235 |
* |
| 236 |
* If there's no data currently buffered and nothing to be flushed, then |
| 237 |
* this method MAY `close()` the stream immediately. |
| 238 |
* |
| 239 |
* If there's still data in the buffer that needs to be flushed first, then |
| 240 |
* this method SHOULD try to write out this data and only then `close()` |
| 241 |
* the stream. |
| 242 |
* Once the stream is closed, it SHOULD emit a `close` event. |
| 243 |
* |
| 244 |
* Note that this interface gives you no control over explicitly flushing |
| 245 |
* the buffered data, as finding the appropriate time for this is beyond the |
| 246 |
* scope of this interface and left up to the implementation of this |
| 247 |
* interface. |
| 248 |
* |
| 249 |
* Many common streams (such as a TCP/IP connection or file-based stream) |
| 250 |
* may choose to buffer all given data and schedule a future flush by using |
| 251 |
* an underlying EventLoop to check when the resource is actually writable. |
| 252 |
* |
| 253 |
* You can optionally pass some final data that is written to the stream |
| 254 |
* before ending the stream. If a non-`null` value is given as `$data`, then |
| 255 |
* this method will behave just like calling `write($data)` before ending |
| 256 |
* with no data. |
| 257 |
* |
| 258 |
* ```php |
| 259 |
* // shorter version |
| 260 |
* $stream->end('bye'); |
| 261 |
* |
| 262 |
* // same as longer version |
| 263 |
* $stream->write('bye'); |
| 264 |
* $stream->end(); |
| 265 |
* ``` |
| 266 |
* |
| 267 |
* After calling this method, the stream MUST switch into a non-writable |
| 268 |
* mode, see also `isWritable()`. |
| 269 |
* This means that no further writes are possible, so any additional |
| 270 |
* `write()` or `end()` calls have no effect. |
| 271 |
* |
| 272 |
* ```php |
| 273 |
* $stream->end(); |
| 274 |
* assert($stream->isWritable() === false); |
| 275 |
* |
| 276 |
* $stream->write('nope'); // NO-OP |
| 277 |
* $stream->end(); // NO-OP |
| 278 |
* ``` |
| 279 |
* |
| 280 |
* If this stream is a `DuplexStreamInterface`, calling this method SHOULD |
| 281 |
* also end its readable side, unless the stream supports half-open mode. |
| 282 |
* In other words, after calling this method, these streams SHOULD switch |
| 283 |
* into non-writable AND non-readable mode, see also `isReadable()`. |
| 284 |
* This implies that in this case, the stream SHOULD NOT emit any `data` |
| 285 |
* or `end` events anymore. |
| 286 |
* Streams MAY choose to use the `pause()` method logic for this, but |
| 287 |
* special care may have to be taken to ensure a following call to the |
| 288 |
* `resume()` method SHOULD NOT continue emitting readable events. |
| 289 |
* |
| 290 |
* Note that this method should not be confused with the `close()` method. |
| 291 |
* |
| 292 |
* @param mixed|string|null $data |
| 293 |
* @return void |
| 294 |
*/ |
| 295 |
public function end($data = null); |
| 296 |
|
| 297 |
/** |
| 298 |
* Closes the stream (forcefully). |
| 299 |
* |
| 300 |
* This method can be used to forcefully close the stream, i.e. close |
| 301 |
* the stream without waiting for any buffered data to be flushed. |
| 302 |
* If there's still data in the buffer, this data SHOULD be discarded. |
| 303 |
* |
| 304 |
* ```php |
| 305 |
* $stream->close(); |
| 306 |
* ``` |
| 307 |
* |
| 308 |
* Once the stream is closed, it SHOULD emit a `close` event. |
| 309 |
* Note that this event SHOULD NOT be emitted more than once, in particular |
| 310 |
* if this method is called multiple times. |
| 311 |
* |
| 312 |
* After calling this method, the stream MUST switch into a non-writable |
| 313 |
* mode, see also `isWritable()`. |
| 314 |
* This means that no further writes are possible, so any additional |
| 315 |
* `write()` or `end()` calls have no effect. |
| 316 |
* |
| 317 |
* ```php |
| 318 |
* $stream->close(); |
| 319 |
* assert($stream->isWritable() === false); |
| 320 |
* |
| 321 |
* $stream->write('nope'); // NO-OP |
| 322 |
* $stream->end(); // NO-OP |
| 323 |
* ``` |
| 324 |
* |
| 325 |
* Note that this method should not be confused with the `end()` method. |
| 326 |
* Unlike the `end()` method, this method does not take care of any existing |
| 327 |
* buffers and simply discards any buffer contents. |
| 328 |
* Likewise, this method may also be called after calling `end()` on a |
| 329 |
* stream in order to stop waiting for the stream to flush its final data. |
| 330 |
* |
| 331 |
* ```php |
| 332 |
* $stream->end(); |
| 333 |
* Loop::addTimer(1.0, function () use ($stream) { |
| 334 |
* $stream->close(); |
| 335 |
* }); |
| 336 |
* ``` |
| 337 |
* |
| 338 |
* If this stream is a `DuplexStreamInterface`, you should also notice |
| 339 |
* how the readable side of the stream also implements a `close()` method. |
| 340 |
* In other words, after calling this method, the stream MUST switch into |
| 341 |
* non-writable AND non-readable mode, see also `isReadable()`. |
| 342 |
* |
| 343 |
* @return void |
| 344 |
* @see ReadableStreamInterface::close() |
| 345 |
*/ |
| 346 |
public function close(); |
| 347 |
} |