Permalink
Browse files

doc: note that `stream.pause` is advisory

  • Loading branch information...
1 parent 70005be commit 5bc07cc90b4fb0a18704bc7b60e120b22fc78df7 @domenic domenic committed with bnoordhuis Apr 9, 2012
Showing with 7 additions and 1 deletion.
  1. +7 −1 doc/api/stream.markdown
View
8 doc/api/stream.markdown
@@ -57,7 +57,13 @@ Makes the data event emit a string instead of a `Buffer`. `encoding` can be
### stream.pause()
-Pauses the incoming `'data'` events.
+Issues an advisory signal to the underlying communication layer, requesting
+that no further data be sent until `resume()` is called.
+
+Note that, due to the advisory nature, certain streams will not be paused
+immediately, and so `'data'` events may be emitted for some indeterminate
+period of time even after `pause()` is called. You may wish to buffer such
+`'data'` events.
### stream.resume()

0 comments on commit 5bc07cc

Please sign in to comment.