翻译错误:如果你在创建writable流时指定了highWaterMark参数......
Ma63d opened this issue · comments
原文:
If you care about high water marks and buffering, .write() returns false when there is more data than the opts.highWaterMark option passed to Writable() in the incoming buffer.
本项目中的翻译:
如果你在创建writable流时指定了highWaterMark参数，那么当没有更多数据写入时，调用.write()方法将会返回false。
本段完全翻译错了，因为实际的情况是，当输入的数据(原文中的 the incoming buffer) 超过了 highWaterMark时，那么此时.write()便会返回false以通知你此时缓存区已满，请勿再写入数据，英文原文的意思也是如此.
具体可以参考Node.js的官方API手册
但是中文版在翻译时却弄反了原作者的意思，并不是当没有更多数据写入时，实则是数据过多，超出缓存区（缓存区的大小由执行构造函数Writable()时的参数opts中的属性opts.highWaterMark来指定，英文原文亦有此含义）。
实际使用时，一般的情况是这样，一般来说一个Writable的流可能是一个网络输出的流或者将内容写入硬盘的流，但是当我们在这个流上执行了过多的.write()任务或者，一次写入的内容长度过大（总之就是导致缓冲区的内容长度超出了highWaterMark参数指定的缓冲区长度），那么.write()就会返回false，所以一般会有如下逻辑(如下情况是将readStream写入writeStream,但是readStream过快):
if (writeStream.write(chunk) === false) { // 如果writeStream数据没有写完，暂停读取流
readStream.pause();
}
用来暂停读取操作，不要急着向Writable流中写入，等到Writable流的drain事件发生，如drain字面含义一样，意即缓冲区的内容已经全部正确的排空了（通过网络输出出去了，或者写入硬盘了等等），那么我们可以readStream.resume()，并继续在Writable流上执行.write操作了，也即英文原版中所说:
If you want to wait for the buffer to empty again, listen for a 'drain' event.