From fc2298602323530bda9efa75f61dfb0e6433b401 Mon Sep 17 00:00:00 2001 From: isaacs Date: Fri, 1 Mar 2013 14:26:35 -0800 Subject: doc: Clarify advisory-ness of stream._read() argument --- doc/api/stream.markdown | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index a30eea3def..ef4848c2ef 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -127,6 +127,13 @@ When data is available, put it into the read queue by calling reading. When `_read` is called again, you should start pushing more data. +The `size` argument is advisory. Implementations where a "read" is a +single call that returns data can use this to know how much data to +fetch. Implementations where that is not relevant, such as TCP or +TLS, may ignore this argument, and simply provide data whenever it +becomes available. There is no need, for example to "wait" until +`size` bytes are available before calling `stream.push(chunk)`. + ### readable.push(chunk) * `chunk` {Buffer | null | String} Chunk of data to push into the read queue -- cgit v1.2.3