This module is for throttling the data rate on a streams2+ Readable
stream.
This is not done by buffering but rather by rate-limited reading in paused mode,
meaning the throttle is relatively close to the source.
Example use case: unlike other throttle modules that use buffering, this can be used to effectively throttle an incoming TCP stream, affecting the other side of the connection as well because the internal Node and OS buffers will congest.
Accuracy can be anywhere from <1% to over 25% depending on the rate and the
kind of source. High rate limits, slower streams and streams with few/small
buffers tend to be throttled more accurately. The utilities in test-util
can be used to perform measurements with socket and file streams.
Just wrap your readable stream in a ThrottledReader
instance, which is also
a Readable
. You can then use the throttled stream in its place.
ThrottledReader
must be the only consumer of the source stream's data!
var ThrottledReader = require('throttled-reader');
var throttledStream = new ThrottledReader(sourceStream, {
rate: 10 * 1024 // In bytes per second
});
throttledStream.pipe(destinationStream);
Constructor:
ThrottledReader(readableStream[, throttleOptions[, streamOptions]])
-
readableStream
is theReadable
to read from. -
throttleOptions
may contain the following options:Option Default Description rate
0 Average rate to throttle to (bytes/sec). Zero means unlimited. cooldownInterval
100 How often to determine whether reading may continue (ms). Lower values are more accurate but also introduce more processing overhead. -
streamOptions
may contain constructor options for the newReadable
.
The data rate can be dynamically changed using getRate()
and setRate(rate)
.