Debian Codegraph @

vendor/react/stream/src/ReadableStreamInterface.php

raw
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 }