stream: Add readable.push(chunk) method

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)
 

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)

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);
+  });
+}