_stream_writable.js 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687
  1. // Copyright Joyent, Inc. and other Node contributors.
  2. //
  3. // Permission is hereby granted, free of charge, to any person obtaining a
  4. // copy of this software and associated documentation files (the
  5. // "Software"), to deal in the Software without restriction, including
  6. // without limitation the rights to use, copy, modify, merge, publish,
  7. // distribute, sublicense, and/or sell copies of the Software, and to permit
  8. // persons to whom the Software is furnished to do so, subject to the
  9. // following conditions:
  10. //
  11. // The above copyright notice and this permission notice shall be included
  12. // in all copies or substantial portions of the Software.
  13. //
  14. // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15. // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16. // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
  17. // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  18. // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  19. // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  20. // USE OR OTHER DEALINGS IN THE SOFTWARE.
  21. // A bit simpler than readable streams.
  22. // Implement an async ._write(chunk, encoding, cb), and it'll handle all
  23. // the drain event emission and buffering.
  24. 'use strict';
  25. /*<replacement>*/
  26. var pna = require('process-nextick-args');
  27. /*</replacement>*/
  28. module.exports = Writable;
  29. /* <replacement> */
  30. function WriteReq(chunk, encoding, cb) {
  31. this.chunk = chunk;
  32. this.encoding = encoding;
  33. this.callback = cb;
  34. this.next = null;
  35. }
  36. // It seems a linked list but it is not
  37. // there will be only 2 of these for each stream
  38. function CorkedRequest(state) {
  39. var _this = this;
  40. this.next = null;
  41. this.entry = null;
  42. this.finish = function () {
  43. onCorkedFinish(_this, state);
  44. };
  45. }
  46. /* </replacement> */
  47. /*<replacement>*/
  48. var asyncWrite = !process.browser && ['v0.10', 'v0.9.'].indexOf(process.version.slice(0, 5)) > -1 ? setImmediate : pna.nextTick;
  49. /*</replacement>*/
  50. /*<replacement>*/
  51. var Duplex;
  52. /*</replacement>*/
  53. Writable.WritableState = WritableState;
  54. /*<replacement>*/
  55. var util = require('core-util-is');
  56. util.inherits = require('inherits');
  57. /*</replacement>*/
  58. /*<replacement>*/
  59. var internalUtil = {
  60. deprecate: require('util-deprecate')
  61. };
  62. /*</replacement>*/
  63. /*<replacement>*/
  64. var Stream = require('./internal/streams/stream');
  65. /*</replacement>*/
  66. /*<replacement>*/
  67. var Buffer = require('safe-buffer').Buffer;
  68. var OurUint8Array = global.Uint8Array || function () {};
  69. function _uint8ArrayToBuffer(chunk) {
  70. return Buffer.from(chunk);
  71. }
  72. function _isUint8Array(obj) {
  73. return Buffer.isBuffer(obj) || obj instanceof OurUint8Array;
  74. }
  75. /*</replacement>*/
  76. var destroyImpl = require('./internal/streams/destroy');
  77. util.inherits(Writable, Stream);
  78. function nop() {}
  79. function WritableState(options, stream) {
  80. Duplex = Duplex || require('./_stream_duplex');
  81. options = options || {};
  82. // Duplex streams are both readable and writable, but share
  83. // the same options object.
  84. // However, some cases require setting options to different
  85. // values for the readable and the writable sides of the duplex stream.
  86. // These options can be provided separately as readableXXX and writableXXX.
  87. var isDuplex = stream instanceof Duplex;
  88. // object stream flag to indicate whether or not this stream
  89. // contains buffers or objects.
  90. this.objectMode = !!options.objectMode;
  91. if (isDuplex) this.objectMode = this.objectMode || !!options.writableObjectMode;
  92. // the point at which write() starts returning false
  93. // Note: 0 is a valid value, means that we always return false if
  94. // the entire buffer is not flushed immediately on write()
  95. var hwm = options.highWaterMark;
  96. var writableHwm = options.writableHighWaterMark;
  97. var defaultHwm = this.objectMode ? 16 : 16 * 1024;
  98. if (hwm || hwm === 0) this.highWaterMark = hwm;else if (isDuplex && (writableHwm || writableHwm === 0)) this.highWaterMark = writableHwm;else this.highWaterMark = defaultHwm;
  99. // cast to ints.
  100. this.highWaterMark = Math.floor(this.highWaterMark);
  101. // if _final has been called
  102. this.finalCalled = false;
  103. // drain event flag.
  104. this.needDrain = false;
  105. // at the start of calling end()
  106. this.ending = false;
  107. // when end() has been called, and returned
  108. this.ended = false;
  109. // when 'finish' is emitted
  110. this.finished = false;
  111. // has it been destroyed
  112. this.destroyed = false;
  113. // should we decode strings into buffers before passing to _write?
  114. // this is here so that some node-core streams can optimize string
  115. // handling at a lower level.
  116. var noDecode = options.decodeStrings === false;
  117. this.decodeStrings = !noDecode;
  118. // Crypto is kind of old and crusty. Historically, its default string
  119. // encoding is 'binary' so we have to make this configurable.
  120. // Everything else in the universe uses 'utf8', though.
  121. this.defaultEncoding = options.defaultEncoding || 'utf8';
  122. // not an actual buffer we keep track of, but a measurement
  123. // of how much we're waiting to get pushed to some underlying
  124. // socket or file.
  125. this.length = 0;
  126. // a flag to see when we're in the middle of a write.
  127. this.writing = false;
  128. // when true all writes will be buffered until .uncork() call
  129. this.corked = 0;
  130. // a flag to be able to tell if the onwrite cb is called immediately,
  131. // or on a later tick. We set this to true at first, because any
  132. // actions that shouldn't happen until "later" should generally also
  133. // not happen before the first write call.
  134. this.sync = true;
  135. // a flag to know if we're processing previously buffered items, which
  136. // may call the _write() callback in the same tick, so that we don't
  137. // end up in an overlapped onwrite situation.
  138. this.bufferProcessing = false;
  139. // the callback that's passed to _write(chunk,cb)
  140. this.onwrite = function (er) {
  141. onwrite(stream, er);
  142. };
  143. // the callback that the user supplies to write(chunk,encoding,cb)
  144. this.writecb = null;
  145. // the amount that is being written when _write is called.
  146. this.writelen = 0;
  147. this.bufferedRequest = null;
  148. this.lastBufferedRequest = null;
  149. // number of pending user-supplied write callbacks
  150. // this must be 0 before 'finish' can be emitted
  151. this.pendingcb = 0;
  152. // emit prefinish if the only thing we're waiting for is _write cbs
  153. // This is relevant for synchronous Transform streams
  154. this.prefinished = false;
  155. // True if the error was already emitted and should not be thrown again
  156. this.errorEmitted = false;
  157. // count buffered requests
  158. this.bufferedRequestCount = 0;
  159. // allocate the first CorkedRequest, there is always
  160. // one allocated and free to use, and we maintain at most two
  161. this.corkedRequestsFree = new CorkedRequest(this);
  162. }
  163. WritableState.prototype.getBuffer = function getBuffer() {
  164. var current = this.bufferedRequest;
  165. var out = [];
  166. while (current) {
  167. out.push(current);
  168. current = current.next;
  169. }
  170. return out;
  171. };
  172. (function () {
  173. try {
  174. Object.defineProperty(WritableState.prototype, 'buffer', {
  175. get: internalUtil.deprecate(function () {
  176. return this.getBuffer();
  177. }, '_writableState.buffer is deprecated. Use _writableState.getBuffer ' + 'instead.', 'DEP0003')
  178. });
  179. } catch (_) {}
  180. })();
  181. // Test _writableState for inheritance to account for Duplex streams,
  182. // whose prototype chain only points to Readable.
  183. var realHasInstance;
  184. if (typeof Symbol === 'function' && Symbol.hasInstance && typeof Function.prototype[Symbol.hasInstance] === 'function') {
  185. realHasInstance = Function.prototype[Symbol.hasInstance];
  186. Object.defineProperty(Writable, Symbol.hasInstance, {
  187. value: function (object) {
  188. if (realHasInstance.call(this, object)) return true;
  189. if (this !== Writable) return false;
  190. return object && object._writableState instanceof WritableState;
  191. }
  192. });
  193. } else {
  194. realHasInstance = function (object) {
  195. return object instanceof this;
  196. };
  197. }
  198. function Writable(options) {
  199. Duplex = Duplex || require('./_stream_duplex');
  200. // Writable ctor is applied to Duplexes, too.
  201. // `realHasInstance` is necessary because using plain `instanceof`
  202. // would return false, as no `_writableState` property is attached.
  203. // Trying to use the custom `instanceof` for Writable here will also break the
  204. // Node.js LazyTransform implementation, which has a non-trivial getter for
  205. // `_writableState` that would lead to infinite recursion.
  206. if (!realHasInstance.call(Writable, this) && !(this instanceof Duplex)) {
  207. return new Writable(options);
  208. }
  209. this._writableState = new WritableState(options, this);
  210. // legacy.
  211. this.writable = true;
  212. if (options) {
  213. if (typeof options.write === 'function') this._write = options.write;
  214. if (typeof options.writev === 'function') this._writev = options.writev;
  215. if (typeof options.destroy === 'function') this._destroy = options.destroy;
  216. if (typeof options.final === 'function') this._final = options.final;
  217. }
  218. Stream.call(this);
  219. }
  220. // Otherwise people can pipe Writable streams, which is just wrong.
  221. Writable.prototype.pipe = function () {
  222. this.emit('error', new Error('Cannot pipe, not readable'));
  223. };
  224. function writeAfterEnd(stream, cb) {
  225. var er = new Error('write after end');
  226. // TODO: defer error events consistently everywhere, not just the cb
  227. stream.emit('error', er);
  228. pna.nextTick(cb, er);
  229. }
  230. // Checks that a user-supplied chunk is valid, especially for the particular
  231. // mode the stream is in. Currently this means that `null` is never accepted
  232. // and undefined/non-string values are only allowed in object mode.
  233. function validChunk(stream, state, chunk, cb) {
  234. var valid = true;
  235. var er = false;
  236. if (chunk === null) {
  237. er = new TypeError('May not write null values to stream');
  238. } else if (typeof chunk !== 'string' && chunk !== undefined && !state.objectMode) {
  239. er = new TypeError('Invalid non-string/buffer chunk');
  240. }
  241. if (er) {
  242. stream.emit('error', er);
  243. pna.nextTick(cb, er);
  244. valid = false;
  245. }
  246. return valid;
  247. }
  248. Writable.prototype.write = function (chunk, encoding, cb) {
  249. var state = this._writableState;
  250. var ret = false;
  251. var isBuf = !state.objectMode && _isUint8Array(chunk);
  252. if (isBuf && !Buffer.isBuffer(chunk)) {
  253. chunk = _uint8ArrayToBuffer(chunk);
  254. }
  255. if (typeof encoding === 'function') {
  256. cb = encoding;
  257. encoding = null;
  258. }
  259. if (isBuf) encoding = 'buffer';else if (!encoding) encoding = state.defaultEncoding;
  260. if (typeof cb !== 'function') cb = nop;
  261. if (state.ended) writeAfterEnd(this, cb);else if (isBuf || validChunk(this, state, chunk, cb)) {
  262. state.pendingcb++;
  263. ret = writeOrBuffer(this, state, isBuf, chunk, encoding, cb);
  264. }
  265. return ret;
  266. };
  267. Writable.prototype.cork = function () {
  268. var state = this._writableState;
  269. state.corked++;
  270. };
  271. Writable.prototype.uncork = function () {
  272. var state = this._writableState;
  273. if (state.corked) {
  274. state.corked--;
  275. if (!state.writing && !state.corked && !state.finished && !state.bufferProcessing && state.bufferedRequest) clearBuffer(this, state);
  276. }
  277. };
  278. Writable.prototype.setDefaultEncoding = function setDefaultEncoding(encoding) {
  279. // node::ParseEncoding() requires lower case.
  280. if (typeof encoding === 'string') encoding = encoding.toLowerCase();
  281. if (!(['hex', 'utf8', 'utf-8', 'ascii', 'binary', 'base64', 'ucs2', 'ucs-2', 'utf16le', 'utf-16le', 'raw'].indexOf((encoding + '').toLowerCase()) > -1)) throw new TypeError('Unknown encoding: ' + encoding);
  282. this._writableState.defaultEncoding = encoding;
  283. return this;
  284. };
  285. function decodeChunk(state, chunk, encoding) {
  286. if (!state.objectMode && state.decodeStrings !== false && typeof chunk === 'string') {
  287. chunk = Buffer.from(chunk, encoding);
  288. }
  289. return chunk;
  290. }
  291. Object.defineProperty(Writable.prototype, 'writableHighWaterMark', {
  292. // making it explicit this property is not enumerable
  293. // because otherwise some prototype manipulation in
  294. // userland will fail
  295. enumerable: false,
  296. get: function () {
  297. return this._writableState.highWaterMark;
  298. }
  299. });
  300. // if we're already writing something, then just put this
  301. // in the queue, and wait our turn. Otherwise, call _write
  302. // If we return false, then we need a drain event, so set that flag.
  303. function writeOrBuffer(stream, state, isBuf, chunk, encoding, cb) {
  304. if (!isBuf) {
  305. var newChunk = decodeChunk(state, chunk, encoding);
  306. if (chunk !== newChunk) {
  307. isBuf = true;
  308. encoding = 'buffer';
  309. chunk = newChunk;
  310. }
  311. }
  312. var len = state.objectMode ? 1 : chunk.length;
  313. state.length += len;
  314. var ret = state.length < state.highWaterMark;
  315. // we must ensure that previous needDrain will not be reset to false.
  316. if (!ret) state.needDrain = true;
  317. if (state.writing || state.corked) {
  318. var last = state.lastBufferedRequest;
  319. state.lastBufferedRequest = {
  320. chunk: chunk,
  321. encoding: encoding,
  322. isBuf: isBuf,
  323. callback: cb,
  324. next: null
  325. };
  326. if (last) {
  327. last.next = state.lastBufferedRequest;
  328. } else {
  329. state.bufferedRequest = state.lastBufferedRequest;
  330. }
  331. state.bufferedRequestCount += 1;
  332. } else {
  333. doWrite(stream, state, false, len, chunk, encoding, cb);
  334. }
  335. return ret;
  336. }
  337. function doWrite(stream, state, writev, len, chunk, encoding, cb) {
  338. state.writelen = len;
  339. state.writecb = cb;
  340. state.writing = true;
  341. state.sync = true;
  342. if (writev) stream._writev(chunk, state.onwrite);else stream._write(chunk, encoding, state.onwrite);
  343. state.sync = false;
  344. }
  345. function onwriteError(stream, state, sync, er, cb) {
  346. --state.pendingcb;
  347. if (sync) {
  348. // defer the callback if we are being called synchronously
  349. // to avoid piling up things on the stack
  350. pna.nextTick(cb, er);
  351. // this can emit finish, and it will always happen
  352. // after error
  353. pna.nextTick(finishMaybe, stream, state);
  354. stream._writableState.errorEmitted = true;
  355. stream.emit('error', er);
  356. } else {
  357. // the caller expect this to happen before if
  358. // it is async
  359. cb(er);
  360. stream._writableState.errorEmitted = true;
  361. stream.emit('error', er);
  362. // this can emit finish, but finish must
  363. // always follow error
  364. finishMaybe(stream, state);
  365. }
  366. }
  367. function onwriteStateUpdate(state) {
  368. state.writing = false;
  369. state.writecb = null;
  370. state.length -= state.writelen;
  371. state.writelen = 0;
  372. }
  373. function onwrite(stream, er) {
  374. var state = stream._writableState;
  375. var sync = state.sync;
  376. var cb = state.writecb;
  377. onwriteStateUpdate(state);
  378. if (er) onwriteError(stream, state, sync, er, cb);else {
  379. // Check if we're actually ready to finish, but don't emit yet
  380. var finished = needFinish(state);
  381. if (!finished && !state.corked && !state.bufferProcessing && state.bufferedRequest) {
  382. clearBuffer(stream, state);
  383. }
  384. if (sync) {
  385. /*<replacement>*/
  386. asyncWrite(afterWrite, stream, state, finished, cb);
  387. /*</replacement>*/
  388. } else {
  389. afterWrite(stream, state, finished, cb);
  390. }
  391. }
  392. }
  393. function afterWrite(stream, state, finished, cb) {
  394. if (!finished) onwriteDrain(stream, state);
  395. state.pendingcb--;
  396. cb();
  397. finishMaybe(stream, state);
  398. }
  399. // Must force callback to be called on nextTick, so that we don't
  400. // emit 'drain' before the write() consumer gets the 'false' return
  401. // value, and has a chance to attach a 'drain' listener.
  402. function onwriteDrain(stream, state) {
  403. if (state.length === 0 && state.needDrain) {
  404. state.needDrain = false;
  405. stream.emit('drain');
  406. }
  407. }
  408. // if there's something in the buffer waiting, then process it
  409. function clearBuffer(stream, state) {
  410. state.bufferProcessing = true;
  411. var entry = state.bufferedRequest;
  412. if (stream._writev && entry && entry.next) {
  413. // Fast case, write everything using _writev()
  414. var l = state.bufferedRequestCount;
  415. var buffer = new Array(l);
  416. var holder = state.corkedRequestsFree;
  417. holder.entry = entry;
  418. var count = 0;
  419. var allBuffers = true;
  420. while (entry) {
  421. buffer[count] = entry;
  422. if (!entry.isBuf) allBuffers = false;
  423. entry = entry.next;
  424. count += 1;
  425. }
  426. buffer.allBuffers = allBuffers;
  427. doWrite(stream, state, true, state.length, buffer, '', holder.finish);
  428. // doWrite is almost always async, defer these to save a bit of time
  429. // as the hot path ends with doWrite
  430. state.pendingcb++;
  431. state.lastBufferedRequest = null;
  432. if (holder.next) {
  433. state.corkedRequestsFree = holder.next;
  434. holder.next = null;
  435. } else {
  436. state.corkedRequestsFree = new CorkedRequest(state);
  437. }
  438. state.bufferedRequestCount = 0;
  439. } else {
  440. // Slow case, write chunks one-by-one
  441. while (entry) {
  442. var chunk = entry.chunk;
  443. var encoding = entry.encoding;
  444. var cb = entry.callback;
  445. var len = state.objectMode ? 1 : chunk.length;
  446. doWrite(stream, state, false, len, chunk, encoding, cb);
  447. entry = entry.next;
  448. state.bufferedRequestCount--;
  449. // if we didn't call the onwrite immediately, then
  450. // it means that we need to wait until it does.
  451. // also, that means that the chunk and cb are currently
  452. // being processed, so move the buffer counter past them.
  453. if (state.writing) {
  454. break;
  455. }
  456. }
  457. if (entry === null) state.lastBufferedRequest = null;
  458. }
  459. state.bufferedRequest = entry;
  460. state.bufferProcessing = false;
  461. }
  462. Writable.prototype._write = function (chunk, encoding, cb) {
  463. cb(new Error('_write() is not implemented'));
  464. };
  465. Writable.prototype._writev = null;
  466. Writable.prototype.end = function (chunk, encoding, cb) {
  467. var state = this._writableState;
  468. if (typeof chunk === 'function') {
  469. cb = chunk;
  470. chunk = null;
  471. encoding = null;
  472. } else if (typeof encoding === 'function') {
  473. cb = encoding;
  474. encoding = null;
  475. }
  476. if (chunk !== null && chunk !== undefined) this.write(chunk, encoding);
  477. // .end() fully uncorks
  478. if (state.corked) {
  479. state.corked = 1;
  480. this.uncork();
  481. }
  482. // ignore unnecessary end() calls.
  483. if (!state.ending && !state.finished) endWritable(this, state, cb);
  484. };
  485. function needFinish(state) {
  486. return state.ending && state.length === 0 && state.bufferedRequest === null && !state.finished && !state.writing;
  487. }
  488. function callFinal(stream, state) {
  489. stream._final(function (err) {
  490. state.pendingcb--;
  491. if (err) {
  492. stream.emit('error', err);
  493. }
  494. state.prefinished = true;
  495. stream.emit('prefinish');
  496. finishMaybe(stream, state);
  497. });
  498. }
  499. function prefinish(stream, state) {
  500. if (!state.prefinished && !state.finalCalled) {
  501. if (typeof stream._final === 'function') {
  502. state.pendingcb++;
  503. state.finalCalled = true;
  504. pna.nextTick(callFinal, stream, state);
  505. } else {
  506. state.prefinished = true;
  507. stream.emit('prefinish');
  508. }
  509. }
  510. }
  511. function finishMaybe(stream, state) {
  512. var need = needFinish(state);
  513. if (need) {
  514. prefinish(stream, state);
  515. if (state.pendingcb === 0) {
  516. state.finished = true;
  517. stream.emit('finish');
  518. }
  519. }
  520. return need;
  521. }
  522. function endWritable(stream, state, cb) {
  523. state.ending = true;
  524. finishMaybe(stream, state);
  525. if (cb) {
  526. if (state.finished) pna.nextTick(cb);else stream.once('finish', cb);
  527. }
  528. state.ended = true;
  529. stream.writable = false;
  530. }
  531. function onCorkedFinish(corkReq, state, err) {
  532. var entry = corkReq.entry;
  533. corkReq.entry = null;
  534. while (entry) {
  535. var cb = entry.callback;
  536. state.pendingcb--;
  537. cb(err);
  538. entry = entry.next;
  539. }
  540. if (state.corkedRequestsFree) {
  541. state.corkedRequestsFree.next = corkReq;
  542. } else {
  543. state.corkedRequestsFree = corkReq;
  544. }
  545. }
  546. Object.defineProperty(Writable.prototype, 'destroyed', {
  547. get: function () {
  548. if (this._writableState === undefined) {
  549. return false;
  550. }
  551. return this._writableState.destroyed;
  552. },
  553. set: function (value) {
  554. // we ignore the value if the stream
  555. // has not been initialized yet
  556. if (!this._writableState) {
  557. return;
  558. }
  559. // backward compatibility, the user is explicitly
  560. // managing destroyed
  561. this._writableState.destroyed = value;
  562. }
  563. });
  564. Writable.prototype.destroy = destroyImpl.destroy;
  565. Writable.prototype._undestroy = destroyImpl.undestroy;
  566. Writable.prototype._destroy = function (err, cb) {
  567. this.end();
  568. cb(err);
  569. };