1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# Stream
Stability: 2 - Unstable
A stream is an abstract interface implemented by various objects in Node.
For example a request to an HTTP server is a stream, as is stdout. Streams
are readable, writable, or both. All streams are instances of `EventEmitter`.
You can load up the Stream base class by doing `require('stream')`.
## Readable Stream
<!--type=class-->
A `Readable Stream` has the following methods, members, and events.
### Event: 'data'
`function (data) { }`
The `'data'` event emits either a `Buffer` (by default) or a string if
`setEncoding()` was used.
Note that the __data will be lost__ if there is no listener when a
`Readable Stream` emits a `'data'` event.
### Event: 'end'
`function () { }`
Emitted when the stream has received an EOF (FIN in TCP terminology).
Indicates that no more `'data'` events will happen. If the stream is also
writable, it may be possible to continue writing.
### Event: 'error'
`function (exception) { }`
Emitted if there was an error receiving data.
### Event: 'close'
`function () { }`
Emitted when the underlying file descriptor has been closed. Not all streams
will emit this. (For example, an incoming HTTP request will not emit
`'close'`.)
### stream.readable
A boolean that is `true` by default, but turns `false` after an `'error'`
occurred, the stream came to an `'end'`, or `destroy()` was called.
### stream.setEncoding(encoding)
Makes the data event emit a string instead of a `Buffer`. `encoding` can be
`'utf8'`, `'ascii'`, or `'base64'`.
### stream.pause()
Pauses the incoming `'data'` events.
### stream.resume()
Resumes the incoming `'data'` events after a `pause()`.
### stream.destroy()
Closes the underlying file descriptor. Stream will not emit any more events.
### stream.destroySoon()
After the write queue is drained, close the file descriptor.
### stream.pipe(destination, [options])
This is a `Stream.prototype` method available on all `Stream`s.
Connects this read stream to `destination` WriteStream. Incoming
data on this stream gets written to `destination`. The destination and source
streams are kept in sync by pausing and resuming as necessary.
This function returns the `destination` stream.
Emulating the Unix `cat` command:
process.stdin.resume();
process.stdin.pipe(process.stdout);
By default `end()` is called on the destination when the source stream emits
`end`, so that `destination` is no longer writable. Pass `{ end: false }` as
`options` to keep the destination stream open.
This keeps `process.stdout` open so that "Goodbye" can be written at the end.
process.stdin.resume();
process.stdin.pipe(process.stdout, { end: false });
process.stdin.on("end", function() {
process.stdout.write("Goodbye\n");
});
## Writable Stream
<!--type=class-->
A `Writable Stream` has the following methods, members, and events.
### Event: 'drain'
`function () { }`
After a `write()` method returned `false`, this event is emitted to
indicate that it is safe to write again.
### Event: 'error'
`function (exception) { }`
Emitted on error with the exception `exception`.
### Event: 'close'
`function () { }`
Emitted when the underlying file descriptor has been closed.
### Event: 'pipe'
`function (src) { }`
Emitted when the stream is passed to a readable stream's pipe method.
### stream.writable
A boolean that is `true` by default, but turns `false` after an `'error'`
occurred or `end()` / `destroy()` was called.
### stream.write(string, [encoding], [fd])
Writes `string` with the given `encoding` to the stream. Returns `true` if
the string has been flushed to the kernel buffer. Returns `false` to
indicate that the kernel buffer is full, and the data will be sent out in
the future. The `'drain'` event will indicate when the kernel buffer is
empty again. The `encoding` defaults to `'utf8'`.
If the optional `fd` parameter is specified, it is interpreted as an integral
file descriptor to be sent over the stream. This is only supported for UNIX
streams, and is silently ignored otherwise. When writing a file descriptor in
this manner, closing the descriptor before the stream drains risks sending an
invalid (closed) FD.
### stream.write(buffer)
Same as the above except with a raw buffer.
### stream.end()
Terminates the stream with EOF or FIN.
This call will allow queued write data to be sent before closing the stream.
### stream.end(string, encoding)
Sends `string` with the given `encoding` and terminates the stream with EOF
or FIN. This is useful to reduce the number of packets sent.
### stream.end(buffer)
Same as above but with a `buffer`.
### stream.destroy()
Closes the underlying file descriptor. Stream will not emit any more events.
Any queued write data will not be sent.
### stream.destroySoon()
After the write queue is drained, close the file descriptor. `destroySoon()`
can still destroy straight away, as long as there is no data left in the queue
for writes.
|
