mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
132 lines
3.4 KiB
Markdown
132 lines
3.4 KiB
Markdown
## Streams
|
|
|
|
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`.
|
|
|
|
## Readable Stream
|
|
|
|
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.
|
|
|
|
### 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 be closed. Not all streams
|
|
will emit this. (For example, an incoming HTTP request will not emit
|
|
`'close'`.)
|
|
|
|
### Event: 'fd'
|
|
|
|
`function (fd) { }`
|
|
|
|
Emitted when a file descriptor is received on the stream. Only UNIX streams
|
|
support this functionality; all others will simply never emit this event.
|
|
|
|
### stream.readable
|
|
|
|
A boolean that is `true` by default, but turns `false` after an `'error'`
|
|
occured, 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.
|
|
|
|
|
|
|
|
## Writable Stream
|
|
|
|
A `Writable Stream` has the following methods, members, and events.
|
|
|
|
### Event: 'drain'
|
|
|
|
`function () { }`
|
|
|
|
Emitted after a `write()` method was called that returned `false` 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.
|
|
|
|
### stream.writeable
|
|
|
|
A boolean that is `true` by default, but turns `false` after an `'error'`
|
|
occurred or `end()` / `destroy()` was called.
|
|
|
|
### stream.write(string, encoding='utf8', [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.
|
|
|
|
### 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.
|