oxmc/nexe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11aaccdf665a561ba0f627bfa13f0ed611588d69
nexe/node-v0.8.14/doc/api/stream.html
T
Craig Condon 11aaccdf66 finally works
2012-11-30 20:11:55 -06:00

323 lines
14 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Stream Node.js v0.8.14 Manual &amp; Documentation</title>
<link rel="stylesheet" href="assets/style.css">
<link rel="stylesheet" href="assets/sh.css">
<link rel="canonical" href="http://nodejs.org/api/stream.html">
</head>
<body class="alt apidoc" id="api-section-stream">
<div id="intro" class="interior">
<a href="/" title="Go back to the home page">
<img id="logo" src="http://nodejs.org/images/logo-light.png" alt="node.js">
</a>
</div>
<div id="content" class="clearfix">
<div id="column2" class="interior">
<ul>
<li><a href="/" class="home">Home</a></li>
<li><a href="/download/" class="download">Download</a></li>
<li><a href="/about/" class="about">About</a></li>
<li><a href="http://search.npmjs.org/" class="npm">npm Registry</a></li>
<li><a href="http://nodejs.org/api/" class="docs current">Docs</a></li>
<li><a href="http://blog.nodejs.org" class="blog">Blog</a></li>
<li><a href="/community/" class="community">Community</a></li>
<li><a href="/logos/" class="logos">Logos</a></li>
<li><a href="http://jobs.nodejs.org/" class="jobs">Jobs</a></li>
</ul>
<p class="twitter"><a href="http://twitter.com/nodejs">@nodejs</a></p>
</div>
<div id="column1" class="interior">
<header>
<h1>Node.js v0.8.14 Manual &amp; Documentation</h1>
<div id="gtoc">
<p>
<a href="index.html" name="toc">Index</a> |
<a href="all.html">View on single page</a> |
<a href="stream.json">View as JSON</a>
</p>
</div>
<hr>
</header>
<div id="toc">
<h2>Table of Contents</h2>
<ul>
<li><a href="#stream_stream">Stream</a><ul>
<li><a href="#stream_readable_stream">Readable Stream</a><ul>
<li><a href="#stream_event_data">Event: &#39;data&#39;</a></li>
<li><a href="#stream_event_end">Event: &#39;end&#39;</a></li>
<li><a href="#stream_event_error">Event: &#39;error&#39;</a></li>
<li><a href="#stream_event_close">Event: &#39;close&#39;</a></li>
<li><a href="#stream_stream_readable">stream.readable</a></li>
<li><a href="#stream_stream_setencoding_encoding">stream.setEncoding([encoding])</a></li>
<li><a href="#stream_stream_pause">stream.pause()</a></li>
<li><a href="#stream_stream_resume">stream.resume()</a></li>
<li><a href="#stream_stream_destroy">stream.destroy()</a></li>
<li><a href="#stream_stream_pipe_destination_options">stream.pipe(destination, [options])</a></li>
</ul>
</li>
<li><a href="#stream_writable_stream">Writable Stream</a><ul>
<li><a href="#stream_event_drain">Event: &#39;drain&#39;</a></li>
<li><a href="#stream_event_error_1">Event: &#39;error&#39;</a></li>
<li><a href="#stream_event_close_1">Event: &#39;close&#39;</a></li>
<li><a href="#stream_event_pipe">Event: &#39;pipe&#39;</a></li>
<li><a href="#stream_stream_writable">stream.writable</a></li>
<li><a href="#stream_stream_write_string_encoding">stream.write(string, [encoding])</a></li>
<li><a href="#stream_stream_write_buffer">stream.write(buffer)</a></li>
<li><a href="#stream_stream_end">stream.end()</a></li>
<li><a href="#stream_stream_end_string_encoding">stream.end(string, encoding)</a></li>
<li><a href="#stream_stream_end_buffer">stream.end(buffer)</a></li>
<li><a href="#stream_stream_destroy_1">stream.destroy()</a></li>
<li><a href="#stream_stream_destroysoon">stream.destroySoon()</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div id="apicontent">
<h1>Stream<span><a class="mark" href="#stream_stream" id="stream_stream">#</a></span></h1>
<pre><code>Stability: 2 - Unstable</code></pre>
<p>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 <a href="events.html#events_class_events_eventemitter">EventEmitter</a>
</p>
<p>You can load up the Stream base class by doing <code>require(&#39;stream&#39;)</code>.
</p>
<h2>Readable Stream<span><a class="mark" href="#stream_readable_stream" id="stream_readable_stream">#</a></span></h2>
<!--type=class-->
<p>A <code>Readable Stream</code> has the following methods, members, and events.
</p>
<h3>Event: &#39;data&#39;<span><a class="mark" href="#stream_event_data" id="stream_event_data">#</a></span></h3>
<p><code>function (data) { }</code>
</p>
<p>The <code>&#39;data&#39;</code> event emits either a <code>Buffer</code> (by default) or a string if
<code>setEncoding()</code> was used.
</p>
<p>Note that the <strong>data will be lost</strong> if there is no listener when a
<code>Readable Stream</code> emits a <code>&#39;data&#39;</code> event.
</p>
<h3>Event: &#39;end&#39;<span><a class="mark" href="#stream_event_end" id="stream_event_end">#</a></span></h3>
<p><code>function () { }</code>
</p>
<p>Emitted when the stream has received an EOF (FIN in TCP terminology).
Indicates that no more <code>&#39;data&#39;</code> events will happen. If the stream is
also writable, it may be possible to continue writing.
</p>
<h3>Event: &#39;error&#39;<span><a class="mark" href="#stream_event_error" id="stream_event_error">#</a></span></h3>
<p><code>function (exception) { }</code>
</p>
<p>Emitted if there was an error receiving data.
</p>
<h3>Event: &#39;close&#39;<span><a class="mark" href="#stream_event_close" id="stream_event_close">#</a></span></h3>
<p><code>function () { }</code>
</p>
<p>Emitted when the underlying resource (for example, the backing file
descriptor) has been closed. Not all streams will emit this.
</p>
<h3>stream.readable<span><a class="mark" href="#stream_stream_readable" id="stream_stream_readable">#</a></span></h3>
<p>A boolean that is <code>true</code> by default, but turns <code>false</code> after an
<code>&#39;error&#39;</code> occurred, the stream came to an <code>&#39;end&#39;</code>, or <code>destroy()</code> was
called.
</p>
<h3>stream.setEncoding([encoding])<span><a class="mark" href="#stream_stream_setencoding_encoding" id="stream_stream_setencoding_encoding">#</a></span></h3>
<p>Makes the <code>&#39;data&#39;</code> event emit a string instead of a <code>Buffer</code>. <code>encoding</code>
can be <code>&#39;utf8&#39;</code>, <code>&#39;utf16le&#39;</code> (<code>&#39;ucs2&#39;</code>), <code>&#39;ascii&#39;</code>, or <code>&#39;hex&#39;</code>. Defaults
to <code>&#39;utf8&#39;</code>.
</p>
<h3>stream.pause()<span><a class="mark" href="#stream_stream_pause" id="stream_stream_pause">#</a></span></h3>
<p>Issues an advisory signal to the underlying communication layer,
requesting that no further data be sent until <code>resume()</code> is called.
</p>
<p>Note that, due to the advisory nature, certain streams will not be
paused immediately, and so <code>&#39;data&#39;</code> events may be emitted for some
indeterminate period of time even after <code>pause()</code> is called. You may
wish to buffer such <code>&#39;data&#39;</code> events.
</p>
<h3>stream.resume()<span><a class="mark" href="#stream_stream_resume" id="stream_stream_resume">#</a></span></h3>
<p>Resumes the incoming <code>&#39;data&#39;</code> events after a <code>pause()</code>.
</p>
<h3>stream.destroy()<span><a class="mark" href="#stream_stream_destroy" id="stream_stream_destroy">#</a></span></h3>
<p>Closes the underlying file descriptor. Stream is no longer <code>writable</code>
nor <code>readable</code>. The stream will not emit any more &#39;data&#39;, or &#39;end&#39;
events. Any queued write data will not be sent. The stream should emit
&#39;close&#39; event once its resources have been disposed of.
</p>
<h3>stream.pipe(destination, [options])<span><a class="mark" href="#stream_stream_pipe_destination_options" id="stream_stream_pipe_destination_options">#</a></span></h3>
<p>This is a <code>Stream.prototype</code> method available on all <code>Stream</code>s.
</p>
<p>Connects this read stream to <code>destination</code> WriteStream. Incoming data on
this stream gets written to <code>destination</code>. The destination and source
streams are kept in sync by pausing and resuming as necessary.
</p>
<p>This function returns the <code>destination</code> stream.
</p>
<p>Emulating the Unix <code>cat</code> command:
</p>
<pre><code>process.stdin.resume(); process.stdin.pipe(process.stdout);</code></pre>
<p>By default <code>end()</code> is called on the destination when the source stream
emits <code>end</code>, so that <code>destination</code> is no longer writable. Pass <code>{ end:
false }</code> as <code>options</code> to keep the destination stream open.
</p>
<p>This keeps <code>process.stdout</code> open so that &quot;Goodbye&quot; can be written at the
end.
</p>
<pre><code>process.stdin.resume();
process.stdin.pipe(process.stdout, { end: false });
process.stdin.on(&quot;end&quot;, function() {
process.stdout.write(&quot;Goodbye\n&quot;); });</code></pre>
<h2>Writable Stream<span><a class="mark" href="#stream_writable_stream" id="stream_writable_stream">#</a></span></h2>
<!--type=class-->
<p>A <code>Writable Stream</code> has the following methods, members, and events.
</p>
<h3>Event: &#39;drain&#39;<span><a class="mark" href="#stream_event_drain" id="stream_event_drain">#</a></span></h3>
<p><code>function () { }</code>
</p>
<p>Emitted when the stream&#39;s write queue empties and it&#39;s safe to write without
buffering again. Listen for it when <code>stream.write()</code> returns <code>false</code>.
</p>
<p>The <code>&#39;drain&#39;</code> event can happen at <em>any</em> time, regardless of whether or not
<code>stream.write()</code> has previously returned <code>false</code>. To avoid receiving unwanted
<code>&#39;drain&#39;</code> events, listen using <code>stream.once()</code>.
</p>
<h3>Event: &#39;error&#39;<span><a class="mark" href="#stream_event_error_1" id="stream_event_error_1">#</a></span></h3>
<p><code>function (exception) { }</code>
</p>
<p>Emitted on error with the exception <code>exception</code>.
</p>
<h3>Event: &#39;close&#39;<span><a class="mark" href="#stream_event_close_1" id="stream_event_close_1">#</a></span></h3>
<p><code>function () { }</code>
</p>
<p>Emitted when the underlying file descriptor has been closed.
</p>
<h3>Event: &#39;pipe&#39;<span><a class="mark" href="#stream_event_pipe" id="stream_event_pipe">#</a></span></h3>
<p><code>function (src) { }</code>
</p>
<p>Emitted when the stream is passed to a readable stream&#39;s pipe method.
</p>
<h3>stream.writable<span><a class="mark" href="#stream_stream_writable" id="stream_stream_writable">#</a></span></h3>
<p>A boolean that is <code>true</code> by default, but turns <code>false</code> after an
<code>&#39;error&#39;</code> occurred or <code>end()</code> / <code>destroy()</code> was called.
</p>
<h3>stream.write(string, [encoding])<span><a class="mark" href="#stream_stream_write_string_encoding" id="stream_stream_write_string_encoding">#</a></span></h3>
<p>Writes <code>string</code> with the given <code>encoding</code> to the stream. Returns <code>true</code>
if the string has been flushed to the kernel buffer. Returns <code>false</code> to
indicate that the kernel buffer is full, and the data will be sent out
in the future. The <code>&#39;drain&#39;</code> event will indicate when the kernel buffer
is empty again. The <code>encoding</code> defaults to <code>&#39;utf8&#39;</code>.
</p>
<h3>stream.write(buffer)<span><a class="mark" href="#stream_stream_write_buffer" id="stream_stream_write_buffer">#</a></span></h3>
<p>Same as the above except with a raw buffer.
</p>
<h3>stream.end()<span><a class="mark" href="#stream_stream_end" id="stream_stream_end">#</a></span></h3>
<p>Terminates the stream with EOF or FIN. This call will allow queued
write data to be sent before closing the stream.
</p>
<h3>stream.end(string, encoding)<span><a class="mark" href="#stream_stream_end_string_encoding" id="stream_stream_end_string_encoding">#</a></span></h3>
<p>Sends <code>string</code> with the given <code>encoding</code> and terminates the stream with
EOF or FIN. This is useful to reduce the number of packets sent.
</p>
<h3>stream.end(buffer)<span><a class="mark" href="#stream_stream_end_buffer" id="stream_stream_end_buffer">#</a></span></h3>
<p>Same as above but with a <code>buffer</code>.
</p>
<h3>stream.destroy()<span><a class="mark" href="#stream_stream_destroy_1" id="stream_stream_destroy_1">#</a></span></h3>
<p>Closes the underlying file descriptor. Stream is no longer <code>writable</code>
nor <code>readable</code>. The stream will not emit any more &#39;data&#39;, or &#39;end&#39;
events. Any queued write data will not be sent. The stream should emit
&#39;close&#39; event once its resources have been disposed of.
</p>
<h3>stream.destroySoon()<span><a class="mark" href="#stream_stream_destroysoon" id="stream_stream_destroysoon">#</a></span></h3>
<p>After the write queue is drained, close the file descriptor.
<code>destroySoon()</code> can still destroy straight away, as long as there is no
data left in the queue for writes.
</p>
</div>
</div>
</div>
<div id="footer">
<ul class="clearfix">
<li><a href="/">Node.js</a></li>
<li><a href="/download/">Download</a></li>
<li><a href="/about/">About</a></li>
<li><a href="http://search.npmjs.org/">npm Registry</a></li>
<li><a href="http://nodejs.org/api/">Docs</a></li>
<li><a href="http://blog.nodejs.org">Blog</a></li>
<li><a href="/community/">Community</a></li>
<li><a href="/logos/">Logos</a></li>
<li><a href="http://jobs.nodejs.org/">Jobs</a></li>
<li><a href="http://twitter.com/nodejs" class="twitter">@nodejs</a></li>
</ul>
<p>Copyright <a href="http://joyent.com/">Joyent, Inc</a>, Node.js is a <a href="/trademark-policy.pdf">trademark</a> of Joyent, Inc. View <a href="https://raw.github.com/joyent/node/v0.8.14/LICENSE">license</a>.</p>
</div>
<script src="../sh_main.js"></script>
<script src="../sh_javascript.min.js"></script>
<script>highlight(undefined, undefined, 'pre');</script>
<script>
window._gaq = [['_setAccount', 'UA-10874194-2'], ['_trackPageview']];
(function(d, t) {
var g = d.createElement(t),
s = d.getElementsByTagName(t)[0];
g.src = '//www.google-analytics.com/ga.js';
s.parentNode.insertBefore(g, s);
}(document, 'script'));
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink