diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 8e3228ca88..bf9da43e16 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -125,6 +125,46 @@ the class that defines it, and should not be called directly by user programs. However, you **are** expected to override this method in your own extension classes. +### readable.push(chunk) + +* `chunk` {Buffer | null | String} Chunk of data to push into the read queue +* return {Boolean} Whether or not more pushes should be performed + +The `Readable` class works by putting data into a read queue to be +pulled out later by calling the `read()` method when the `'readable'` +event fires. + +The `push()` method will explicitly insert some data into the read +queue. If it is called with `null` then it will signal the end of the +data. + +In some cases, you may be wrapping a lower-level source which has some +sort of pause/resume mechanism, and a data callback. In those cases, +you could wrap the low-level source object by doing something like +this: + +```javascript +// source is an object with readStop() and readStart() methods, +// and an `ondata` member that gets called when it has data, and +// an `onend` member that gets called when the data is over. + +var stream = new Readable(); + +source.ondata = function(chunk) { + // if push() returns false, then we need to stop reading from source + if (!stream.push(chunk)) + source.readStop(); +}; + +source.onend = function() { + stream.push(null); +}; + +// _read will be called when the stream wants to pull more data in +stream._read = function(size, cb) { + source.readStart(); +}; +``` ### readable.wrap(stream) diff --git a/lib/_stream_readable.js b/lib/_stream_readable.js index d82ecaff30..bd9126baef 100644 --- a/lib/_stream_readable.js +++ b/lib/_stream_readable.js @@ -94,6 +94,21 @@ function Readable(options) { Stream.call(this); } +// Manually shove something into the read() buffer. +// This returns true if the highWaterMark has not been hit yet, +// similar to how Writable.write() returns true if you should +// write() some more. +Readable.prototype.push = function(chunk) { + var rs = this._readableState; + rs.onread(null, chunk); + + // if it's past the high water mark, we can push in some more. + // Also, if it's still within the lowWaterMark, we can stand some + // more bytes. This is to work around cases where hwm=0 and + // lwm=0, such as the repl. + return rs.length < rs.highWaterMark || rs.length <= rs.lowWaterMark; +}; + // backwards compatibility. Readable.prototype.setEncoding = function(enc) { if (!StringDecoder) diff --git a/test/simple/test-stream2-push.js b/test/simple/test-stream2-push.js new file mode 100644 index 0000000000..a4881c453b --- /dev/null +++ b/test/simple/test-stream2-push.js @@ -0,0 +1,139 @@ +// Copyright Joyent, Inc. and other Node contributors. +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the +// "Software"), to deal in the Software without restriction, including +// without limitation the rights to use, copy, modify, merge, publish, +// distribute, sublicense, and/or sell copies of the Software, and to permit +// persons to whom the Software is furnished to do so, subject to the +// following conditions: +// +// The above copyright notice and this permission notice shall be included +// in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE +// USE OR OTHER DEALINGS IN THE SOFTWARE. + +var common = require('../common.js'); +var stream = require('stream'); +var Readable = stream.Readable; +var Writable = stream.Writable; +var assert = require('assert'); + +var util = require('util'); +var EE = require('events').EventEmitter; + + +// a mock thing a bit like the net.Socket/tcp_wrap.handle interaction + +var stream = new Readable({ + lowWaterMark: 0, + highWaterMark: 16, + encoding: 'utf8' +}); + +var source = new EE; + +stream._read = function() { + console.error('stream._read'); + readStart(); +}; + +var ended = false; +stream.on('end', function() { + ended = true; +}); + +source.on('data', function(chunk) { + var ret = stream.push(chunk); + console.error('data', stream._readableState.length); + if (!ret) + readStop(); +}); + +source.on('end', function() { + stream.push(null); +}); + +var reading = false; + +function readStart() { + console.error('readStart'); + reading = true; +} + +function readStop() { + console.error('readStop'); + reading = false; + process.nextTick(function() { + var r = stream.read(); + if (r !== null) + writer.write(r); + }); +} + +var writer = new Writable({ + decodeStrings: false +}); + +var written = []; + +var expectWritten = + [ 'asdfgasdfgasdfgasdfg', + 'asdfgasdfgasdfgasdfg', + 'asdfgasdfgasdfgasdfg', + 'asdfgasdfgasdfgasdfg', + 'asdfgasdfgasdfgasdfg', + 'asdfgasdfgasdfgasdfg' ]; + +writer._write = function(chunk, cb) { + console.error('WRITE %s', chunk[0]); + written.push(chunk[0]); + process.nextTick(cb); +}; + +writer.on('finish', finish); + + +// now emit some chunks. + +var chunk = "asdfg"; + +var set = 0; +readStart(); +data(); +function data() { + assert(reading); + source.emit('data', chunk); + assert(reading); + source.emit('data', chunk); + assert(reading); + source.emit('data', chunk); + assert(reading); + source.emit('data', chunk); + assert(!reading); + if (set++ < 5) + setTimeout(data, 10); + else + end(); +} + +function finish() { + console.error('finish'); + assert.deepEqual(written, expectWritten); + console.log('ok'); +} + +function end() { + source.emit('end'); + assert(!reading); + writer.end(stream.read()); + setTimeout(function() { + assert(ended); + }); +}