Debian Codegraph @

vendor/react/stream/src/WritableStreamInterface.php

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