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 whenever an 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 MAY be emitted any number of times, which should be zero
73: * times if this is a stream that is successfully terminated.
74: * It SHOULD be emitted whenever the stream detects an error, such as a
75: * transmission error.
76: * It SHOULD NOT be emitted after a `close` event.
77: *
78: * Many common streams (such as a TCP/IP connection or a file-based stream)
79: * only deal with data transmission and may choose
80: * to only emit this for a fatal transmission error once and will thus
81: * likely close (terminate) the stream in response.
82: * If this is a fatal error that results in the stream being closed, it
83: * SHOULD be followed by a `close` event.
84: *
85: * Other higher-level protocols may choose to keep the stream alive after
86: * this event, if they can recover from an error condition.
87: *
88: * If this stream is a `DuplexStreamInterface`, you should also notice
89: * how the readable side of the stream also implements an `error` event.
90: * In other words, an error may occur while either reading or writing the
91: * stream which should result in the same error processing.
92: *
93: * close event:
94: * The `close` event will be emitted once the stream closes (terminates).
95: *
96: * ```php
97: * $stream->on('close', function () {
98: * echo 'CLOSED';
99: * });
100: * ```
101: *
102: * This event SHOULD be emitted once or never at all, depending on whether
103: * the stream ever terminates.
104: * It SHOULD NOT be emitted after a previous `close` event.
105: *
106: * After the stream is closed, it MUST switch to non-writable mode,
107: * see also `isWritable()`.
108: *
109: * This event SHOULD be emitted whenever the stream closes, irrespective of
110: * whether this happens implicitly due to an unrecoverable error or
111: * explicitly when either side closes the stream.
112: *
113: * Many common streams (such as a TCP/IP connection or a file-based stream)
114: * will likely choose to emit this event after flushing the buffer from
115: * the `end()` method, after receiving a *successful* `end` event or after
116: * a fatal transmission `error` event.
117: *
118: * If this stream is a `DuplexStreamInterface`, you should also notice
119: * how the readable side of the stream also implements a `close` event.
120: * In other words, after receiving this event, the stream MUST switch into
121: * non-writable AND non-readable mode, see also `isReadable()`.
122: * Note that this event should not be confused with the `end` event.
123: *
124: * @see EventEmitterInterface
125: * @see DuplexStreamInterface
126: */
127: interface WritableStreamInterface extends EventEmitterInterface
128: {
129: /**
130: * Checks whether this stream is in a writable state (not closed already).
131: *
132: * This method can be used to check if the stream still accepts writing
133: * any data or if it is ended or closed already.
134: * Writing any data to a non-writable stream is a NO-OP:
135: *
136: * ```php
137: * assert($stream->isWritable() === false);
138: *
139: * $stream->write('end'); // NO-OP
140: * $stream->end('end'); // NO-OP
141: * ```
142: *
143: * A successfully opened stream always MUST start in writable mode.
144: *
145: * Once the stream ends or closes, it MUST switch to non-writable mode.
146: * This can happen any time, explicitly through `end()` or `close()` or
147: * implicitly due to a remote close or an unrecoverable transmission error.
148: * Once a stream has switched to non-writable mode, it MUST NOT transition
149: * back to writable mode.
150: *
151: * If this stream is a `DuplexStreamInterface`, you should also notice
152: * how the readable side of the stream also implements an `isReadable()`
153: * method. Unless this is a half-open duplex stream, they SHOULD usually
154: * have the same return value.
155: *
156: * @return bool
157: */
158: public function isWritable();
159:
160: /**
161: * Write some data into the stream.
162: *
163: * A successful write MUST be confirmed with a boolean `true`, which means
164: * that either the data was written (flushed) immediately or is buffered and
165: * scheduled for a future write. Note that this interface gives you no
166: * control over explicitly flushing the buffered data, as finding the
167: * appropriate time for this is beyond the scope of this interface and left
168: * up to the implementation of this interface.
169: *
170: * Many common streams (such as a TCP/IP connection or file-based stream)
171: * may choose to buffer all given data and schedule a future flush by using
172: * an underlying EventLoop to check when the resource is actually writable.
173: *
174: * If a stream cannot handle writing (or flushing) the data, it SHOULD emit
175: * an `error` event and MAY `close()` the stream if it can not recover from
176: * this error.
177: *
178: * If the internal buffer is full after adding `$data`, then `write()`
179: * SHOULD return `false`, indicating that the caller should stop sending
180: * data until the buffer drains.
181: * The stream SHOULD send a `drain` event once the buffer is ready to accept
182: * more data.
183: *
184: * Similarly, if the the stream is not writable (already in a closed state)
185: * it MUST NOT process the given `$data` and SHOULD return `false`,
186: * indicating that the caller should stop sending data.
187: *
188: * The given `$data` argument MAY be of mixed type, but it's usually
189: * recommended it SHOULD be a `string` value or MAY use a type that allows
190: * representation as a `string` for maximum compatibility.
191: *
192: * Many common streams (such as a TCP/IP connection or a file-based stream)
193: * will only accept the raw (binary) payload data that is transferred over
194: * the wire as chunks of `string` values.
195: *
196: * Due to the stream-based nature of this, the sender may send any number
197: * of chunks with varying sizes. There are no guarantees that these chunks
198: * will be received with the exact same framing the sender intended to send.
199: * In other words, many lower-level protocols (such as TCP/IP) transfer the
200: * data in chunks that may be anywhere between single-byte values to several
201: * dozens of kilobytes. You may want to apply a higher-level protocol to
202: * these low-level data chunks in order to achieve proper message framing.
203: *
204: * @param mixed|string $data
205: * @return bool
206: */
207: public function write($data);
208:
209: /**
210: * Successfully ends the stream (after optionally sending some final data).
211: *
212: * This method can be used to successfully end the stream, i.e. close
213: * the stream after sending out all data that is currently buffered.
214: *
215: * ```php
216: * $stream->write('hello');
217: * $stream->write('world');
218: * $stream->end();
219: * ```
220: *
221: * If there's no data currently buffered and nothing to be flushed, then
222: * this method MAY `close()` the stream immediately.
223: *
224: * If there's still data in the buffer that needs to be flushed first, then
225: * this method SHOULD try to write out this data and only then `close()`
226: * the stream.
227: * Once the stream is closed, it SHOULD emit a `close` event.
228: *
229: * Note that this interface gives you no control over explicitly flushing
230: * the buffered data, as finding the appropriate time for this is beyond the
231: * scope of this interface and left up to the implementation of this
232: * interface.
233: *
234: * Many common streams (such as a TCP/IP connection or file-based stream)
235: * may choose to buffer all given data and schedule a future flush by using
236: * an underlying EventLoop to check when the resource is actually writable.
237: *
238: * You can optionally pass some final data that is written to the stream
239: * before ending the stream. If a non-`null` value is given as `$data`, then
240: * this method will behave just like calling `write($data)` before ending
241: * with no data.
242: *
243: * ```php
244: * // shorter version
245: * $stream->end('bye');
246: *
247: * // same as longer version
248: * $stream->write('bye');
249: * $stream->end();
250: * ```
251: *
252: * After calling this method, the stream MUST switch into a non-writable
253: * mode, see also `isWritable()`.
254: * This means that no further writes are possible, so any additional
255: * `write()` or `end()` calls have no effect.
256: *
257: * ```php
258: * $stream->end();
259: * assert($stream->isWritable() === false);
260: *
261: * $stream->write('nope'); // NO-OP
262: * $stream->end(); // NO-OP
263: * ```
264: *
265: * If this stream is a `DuplexStreamInterface`, calling this method SHOULD
266: * also end its readable side, unless the stream supports half-open mode.
267: * In other words, after calling this method, these streams SHOULD switch
268: * into non-writable AND non-readable mode, see also `isReadable()`.
269: * This implies that in this case, the stream SHOULD NOT emit any `data`
270: * or `end` events anymore.
271: * Streams MAY choose to use the `pause()` method logic for this, but
272: * special care may have to be taken to ensure a following call to the
273: * `resume()` method SHOULD NOT continue emitting readable events.
274: *
275: * Note that this method should not be confused with the `close()` method.
276: *
277: * @param mixed|string|null $data
278: * @return void
279: */
280: public function end($data = null);
281:
282: /**
283: * Closes the stream (forcefully).
284: *
285: * This method can be used to forcefully close the stream, i.e. close
286: * the stream without waiting for any buffered data to be flushed.
287: * If there's still data in the buffer, this data SHOULD be discarded.
288: *
289: * ```php
290: * $stream->close();
291: * ```
292: *
293: * Once the stream is closed, it SHOULD emit a `close` event.
294: * Note that this event SHOULD NOT be emitted more than once, in particular
295: * if this method is called multiple times.
296: *
297: * After calling this method, the stream MUST switch into a non-writable
298: * mode, see also `isWritable()`.
299: * This means that no further writes are possible, so any additional
300: * `write()` or `end()` calls have no effect.
301: *
302: * ```php
303: * $stream->close();
304: * assert($stream->isWritable() === false);
305: *
306: * $stream->write('nope'); // NO-OP
307: * $stream->end(); // NO-OP
308: * ```
309: *
310: * Note that this method should not be confused with the `end()` method.
311: * Unlike the `end()` method, this method does not take care of any existing
312: * buffers and simply discards any buffer contents.
313: * Likewise, this method may also be called after calling `end()` on a
314: * stream in order to stop waiting for the stream to flush its final data.
315: *
316: * ```php
317: * $stream->end();
318: * $loop->addTimer(1.0, function () use ($stream) {
319: * $stream->close();
320: * });
321: * ```
322: *
323: * If this stream is a `DuplexStreamInterface`, you should also notice
324: * how the readable side of the stream also implements a `close()` method.
325: * In other words, after calling this method, the stream MUST switch into
326: * non-writable AND non-readable mode, see also `isReadable()`.
327: *
328: * @return void
329: * @see ReadableStreamInterface::close()
330: */
331: public function close();
332: }
333: