Commit 7b656b0d585 for nodejs
commit 7b656b0d585c4aaefa5ce0db9a13ff94950698c0
Author: James M Snell <jasnell@gmail.com>
Date: Wed Oct 7 12:30:17 2026 +0000
stream: read stream/iter from() sync sources without a generator
from() read sync iterable sources with a sync generator doing
for...of over the source, resumed for every batch. Its next() calls
went through FunctionPrototypeCall(), which V8 does not inline for the
next() of a generator.
Read the source with SyncSourceReader, which does what that generator
did, written out by hand: it collects single chunks into batches,
splits oversized batches, flushes before other values, and closes the
source as for...of does on return(), throw() and cancellation. It
calls the next() of a generator as the constant
%GeneratorPrototype%.next, and an own next() method as
iterator.next(), so that V8 can inline either. Like for...of, it reads
next() only once.
Iterating from() over a sync source yielding one-chunk batches is about
15% faster, and over a generator yielding single chunks about 6-11%
faster. Piping a sync source to a writer is about 20% faster.
The microtask that keeps the normalizer busy until the tick after each
batch, for async generator parity, is the remaining per-batch cost;
note it.
Assisted-by: OpenCode
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/66504
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
diff --git a/lib/internal/streams/iter/from.js b/lib/internal/streams/iter/from.js
index 23b7021a649..d32d2353bdc 100644
--- a/lib/internal/streams/iter/from.js
+++ b/lib/internal/streams/iter/from.js
@@ -15,6 +15,8 @@ const {
DataViewPrototypeGetByteOffset,
FunctionPrototypeCall,
ObjectFreeze,
+ ObjectGetOwnPropertyDescriptor,
+ ObjectGetPrototypeOf,
ObjectSetPrototypeOf,
PromisePrototypeThen,
PromiseReject,
@@ -41,6 +43,7 @@ const { lazyDOMException } = require('internal/util');
const {
isAnyArrayBuffer,
+ isGeneratorObject,
isPromise,
isTypedArray,
isUint8Array,
@@ -1119,63 +1122,237 @@ function normalizeAsyncSource(source, context) {
}
// A value of a sync source that is not a Uint8Array or a Uint8Array[]
-// batch, yielded by readSyncSource() to be normalized asynchronously.
+// batch, returned by SyncSourceReader to be normalized asynchronously.
function SyncSourceValue(value) {
this.value = value;
}
SyncSourceValue.prototype = ObjectFreeze({ __proto__: null });
/**
- * Read a sync iterable source for from(): yields Uint8Array[] batches,
+ * Read a sync iterable source for from(): returns Uint8Array[] batches,
* collecting single Uint8Arrays into batches of up to FROM_BATCH_SIZE
* chunks, and a SyncSourceValue for any other value, after the chunks
* collected before it.
- * @param {Iterable} source
- * @param {object} context
- * @yields {Uint8Array[]|SyncSourceValue}
+ *
+ * This is what a sync generator doing `for (const value of source)` would
+ * yield, written out by hand, as it runs for every batch: next(), return()
+ * and throw() behave as that generator's do. The source is closed, as
+ * for...of closes it, when the reader is returned or thrown into while it
+ * is reading the source, or when the normalization is found cancelled;
+ * errors closing it are ignored for throw() and cancellation. An error from
+ * the source's next() or [Symbol.iterator]() ends the reader without
+ * closing the source.
*/
-function* readSyncSource(source, context) {
- throwIfNormalizationCancelled(context);
- if (!isSyncIterable(source)) {
- throw new ERR_INVALID_ARG_TYPE(
- 'source', ['Iterable', 'AsyncIterable'], source);
- }
- let batch = [];
- for (const value of source) {
- throwIfNormalizationCancelled(context);
- // Fast path 1: value is already a Uint8Array[] batch
- if (isUint8ArrayBatch(value)) {
- // Flush any accumulated batch first
- if (batch.length > 0) {
- yield batch;
- batch = [];
+// %GeneratorPrototype%.next, taken before user code runs.
+const GeneratorPrototypeNext =
+ ObjectGetPrototypeOf(function*() {}).prototype.next;
+
+// How a SyncSourceReader calls the next() of its source's iterator.
+const kNextOwn = 1;
+const kNextGenerator = 2;
+
+// The states of a SyncSourceReader: not started, reading the source, done.
+const kReaderStart = 0;
+const kReaderActive = 1;
+const kReaderDone = 2;
+
+class SyncSourceReader {
+ #source;
+ #context;
+ #iterator = null;
+ #next = null;
+ // kNextGenerator if the source's iterator is a generator whose next() is
+ // %GeneratorPrototype%.next, which is then called as a constant; kNextOwn
+ // if its next() is an own data property, which is then called as
+ // `iterator.next()`; otherwise 0, and #next is called with
+ // FunctionPrototypeCall(). Calls V8 can inline make reading single chunks
+ // faster. (Generators of different generator functions don't share a map,
+ // so for them `iterator.next()` would be a megamorphic load per chunk.)
+ #direct = 0;
+ #state = kReaderStart;
+ // Single Uint8Arrays read and not yet returned.
+ #batch = [];
+ // A value to return on the next call, after the batch returned before it.
+ #pending = undefined;
+ // A batch larger than FROM_BATCH_SIZE being returned in slices, and the
+ // offset of the next slice.
+ #large = null;
+ #offset = 0;
+
+ constructor(source, context) {
+ this.#source = source;
+ this.#context = context;
+ }
+
+ next() {
+ switch (this.#state) {
+ case kReaderDone:
+ return new IterResult(true, undefined);
+ case kReaderStart:
+ this.#start();
+ break;
+ }
+ if (this.#pending !== undefined) {
+ const value = this.#pending;
+ this.#pending = undefined;
+ return new IterResult(false, value);
+ }
+ if (this.#large !== null) return new IterResult(false, this.#nextSlice());
+ // Read into locals: the loop runs for every chunk of the source.
+ const iterator = this.#iterator;
+ const next = this.#next;
+ const direct = this.#direct;
+ const context = this.#context;
+ const batch = this.#batch;
+ for (;;) {
+ let value;
+ try {
+ const result = direct === kNextGenerator ?
+ FunctionPrototypeCall(GeneratorPrototypeNext, iterator) :
+ direct === kNextOwn ? iterator.next() :
+ FunctionPrototypeCall(next, iterator);
+ if ((typeof result !== 'object' && typeof result !== 'function') ||
+ result === null) {
+ throw new ERR_INVALID_RETURN_VALUE(
+ 'an object', 'iterator.next()', result);
+ }
+ if (result.done) {
+ this.#state = kReaderDone;
+ if (batch.length > 0) {
+ return new IterResult(false, this.#takeBatch());
+ }
+ return new IterResult(true, undefined);
+ }
+ value = result.value;
+ } catch (error) {
+ this.#state = kReaderDone;
+ throw error;
}
- if (value.length <= FROM_BATCH_SIZE) {
- if (value.length !== 0) yield value;
- } else {
- yield* yieldBoundedBatch(value);
+ if (context?.cancelled) {
+ this.#close(true);
+ throw context.reason;
}
- continue;
- }
- // Fast path 2: value is a single Uint8Array (very common)
- if (isUint8Array(value)) {
- batch[batch.length] = value;
- if (batch.length === FROM_BATCH_SIZE) {
- yield batch;
- batch = [];
+ // Fast path 1: value is a single Uint8Array (very common). Checking
+ // ArrayIsArray() first keeps batches from paying for isUint8Array().
+ const isArray = ArrayIsArray(value);
+ if (!isArray && isUint8Array(value)) {
+ batch[batch.length] = value;
+ if (batch.length === FROM_BATCH_SIZE) {
+ return new IterResult(false, this.#takeBatch());
+ }
+ continue;
}
- continue;
+ // Fast path 2: value is already a Uint8Array[] batch
+ if (isArray && isUint8ArrayBatch(value)) {
+ if (value.length === 0) {
+ if (batch.length > 0) {
+ return new IterResult(false, this.#takeBatch());
+ }
+ continue;
+ }
+ let ready = value;
+ if (value.length > FROM_BATCH_SIZE) {
+ this.#large = value;
+ this.#offset = 0;
+ ready = undefined;
+ }
+ // Flush any accumulated batch first
+ if (batch.length > 0) {
+ this.#pending = ready;
+ return new IterResult(false, this.#takeBatch());
+ }
+ return new IterResult(false, ready ?? this.#nextSlice());
+ }
+ // Slow path: flush, then have the value normalized
+ const sourceValue = new SyncSourceValue(value);
+ if (batch.length > 0) {
+ this.#pending = sourceValue;
+ return new IterResult(false, this.#takeBatch());
+ }
+ return new IterResult(false, sourceValue);
}
- // Slow path: flush, then have the value normalized
- if (batch.length > 0) {
- yield batch;
- batch = [];
+ }
+
+ return() {
+ const state = this.#state;
+ this.#state = kReaderDone;
+ this.#pending = undefined;
+ this.#large = null;
+ if (state === kReaderActive) this.#close(false);
+ return new IterResult(true, undefined);
+ }
+
+ throw(error) {
+ const state = this.#state;
+ this.#state = kReaderDone;
+ this.#pending = undefined;
+ this.#large = null;
+ if (state === kReaderActive) this.#close(true);
+ throw error;
+ }
+
+ #start() {
+ this.#state = kReaderActive;
+ try {
+ throwIfNormalizationCancelled(this.#context);
+ const source = this.#source;
+ if (!isSyncIterable(source)) {
+ throw new ERR_INVALID_ARG_TYPE(
+ 'source', ['Iterable', 'AsyncIterable'], source);
+ }
+ const iterator = source[SymbolIterator]();
+ const next = iterator.next;
+ this.#iterator = iterator;
+ this.#next = next;
+ if (isGeneratorObject(iterator) && next === GeneratorPrototypeNext) {
+ this.#direct = kNextGenerator;
+ } else if (typeof iterator === 'object' && iterator !== null) {
+ const descriptor = ObjectGetOwnPropertyDescriptor(iterator, 'next');
+ if (descriptor !== undefined && descriptor.value === next) {
+ this.#direct = kNextOwn;
+ }
+ }
+ } catch (error) {
+ this.#state = kReaderDone;
+ throw error;
}
- yield new SyncSourceValue(value);
}
- // Yield any remaining batched values
- if (batch.length > 0) {
- yield batch;
+
+ #takeBatch() {
+ const batch = this.#batch;
+ this.#batch = [];
+ return batch;
+ }
+
+ #nextSlice() {
+ const large = this.#large;
+ const offset = this.#offset;
+ this.#offset = offset + FROM_BATCH_SIZE;
+ if (this.#offset >= large.length) this.#large = null;
+ return ArrayPrototypeSlice(large, offset, offset + FROM_BATCH_SIZE);
+ }
+
+ // Close the source as for...of does: errors are ignored if `quiet` (an
+ // error is being thrown), and otherwise thrown, as is a result of
+ // return() that is not an object.
+ #close(quiet) {
+ this.#state = kReaderDone;
+ const iterator = this.#iterator;
+ let result;
+ try {
+ const returnMethod = iterator.return;
+ if (returnMethod === undefined || returnMethod === null) return;
+ result = FunctionPrototypeCall(returnMethod, iterator);
+ } catch (error) {
+ if (quiet) return;
+ throw error;
+ }
+ if (!quiet &&
+ ((typeof result !== 'object' && typeof result !== 'function') ||
+ result === null)) {
+ throw new ERR_INVALID_RETURN_VALUE(
+ 'an object', 'iterator.return()', result);
+ }
}
}
@@ -1184,19 +1361,19 @@ function* readSyncSource(source, context) {
* Uint8Array, without an async generator layer for every batch (see
* createAsyncSourceNormalizer()).
*
- * The source is read by the sync generator readSyncSource(), so for...of
- * reads and closes it, and this iterator only adds the asynchronous
- * normalization of values that need it. Operations on the generator mirror
- * those on the async generator this replaces: return() and throw() are
- * passed to it, after closing the value being normalized, and an error
- * normalizing a value is thrown into it, so that for...of closes the source
- * as for an error in the loop body.
+ * The source is read by a SyncSourceReader, which reads and closes it as
+ * for...of does, and this iterator only adds the asynchronous normalization
+ * of values that need it. Operations on the reader mirror those on the
+ * async generator this replaces: return() and throw() are passed to it,
+ * after closing the value being normalized, and an error normalizing a
+ * value is thrown into it, so that the source is closed as for an error in
+ * the body of a for...of loop.
* @param {Iterable} source
* @param {object} context
* @returns {object} An object with next(), return() and throw().
*/
function createSyncSourceNormalizer(source, context) {
- const reader = readSyncSource(source, context);
+ const reader = new SyncSourceReader(source, context);
let done = false;
// A normalizeAsyncSourceValue() generator for the value being normalized.
let valueBatches = null;
@@ -1206,6 +1383,11 @@ function createSyncSourceNormalizer(source, context) {
// until the tick after a yield or return (both await their operand), so
// that a next(), return() or throw() made synchronously after this one is
// queued behind it; do the same.
+ // TODO(@jasnell): This costs a microtask per batch. Running a call made
+ // while the previous one has finished synchronously right away would make
+ // for-await over from(syncSource) about 1.3x faster, at the cost of this
+ // async generator parity for calls made back to back without awaiting
+ // (see testFromSyncSourceQueuesBehindReturn).
function finish(result) {
PromisePrototypeThen(kResolvedPromise, release);
return result;
diff --git a/test/parallel/test-stream-iter-from-async.js b/test/parallel/test-stream-iter-from-async.js
index cfbb46fa9b6..44befd8eb7e 100644
--- a/test/parallel/test-stream-iter-from-async.js
+++ b/test/parallel/test-stream-iter-from-async.js
@@ -724,6 +724,78 @@ async function testFromSyncSourceBatching() {
]);
}
+async function testFromSyncSourceLargeAndEmptyBatches() {
+ // Batches of more than 128 chunks are split, after the chunks collected
+ // before them; empty batches only flush collected chunks. Returning while
+ // a batch is split closes the source, returning after its last batch
+ // does not.
+ const large = Array.from({ length: 300 }, () => new Uint8Array(1));
+ let log = [];
+ let iterator = from(createLoggedSyncSource(log, [
+ Uint8Array.of(1), [], [], large, Uint8Array.of(2),
+ ]))[Symbol.asyncIterator]();
+ for (let i = 0; i < 6; i++) await settle(log, `result ${i}`, iterator.next());
+ assert.deepStrictEqual(log, [
+ 'iterator', 'next 0', 'next 1', 'result 0: 1', 'next 2', 'next 3',
+ 'result 1: 128', 'result 2: 128', 'result 3: 44', 'next 4', 'next 5',
+ 'result 4: 1', 'result 5: done',
+ ]);
+
+ log = [];
+ iterator = from(createLoggedSyncSource(log, [large]))[
+ Symbol.asyncIterator]();
+ await settle(log, 'result', iterator.next());
+ await settle(log, 'return', iterator.return());
+ assert.deepStrictEqual(log, [
+ 'iterator', 'next 0', 'result: 128', 'return', 'return: done',
+ ]);
+
+ // A result whose value getter throws ends the iteration without closing
+ // the source.
+ log = [];
+ const source = {
+ [Symbol.iterator]() {
+ return {
+ next() {
+ log.push('next');
+ return { done: false, get value() { throw new Error('getter'); } };
+ },
+ return() {
+ log.push('return');
+ return { done: true };
+ },
+ };
+ },
+ };
+ iterator = from(source)[Symbol.asyncIterator]();
+ await settle(log, 'result 0', iterator.next());
+ await settle(log, 'result 1', iterator.next());
+ assert.deepStrictEqual(log, ['next', 'result 0: getter', 'result 1: done']);
+
+ // The next() method of the source's iterator is read once, as for...of
+ // reads it.
+ let reads = 0;
+ let count = 0;
+ const accessorSource = {
+ [Symbol.iterator]() {
+ return {
+ get next() {
+ reads++;
+ return () => (count < 3 ?
+ { done: false, value: [Uint8Array.of(count++)] } :
+ { done: true, value: undefined });
+ },
+ };
+ },
+ };
+ const chunks = [];
+ for await (const batch of from(accessorSource)) chunks.push(...batch);
+ assert.deepStrictEqual(chunks, [
+ Uint8Array.of(0), Uint8Array.of(1), Uint8Array.of(2),
+ ]);
+ assert.strictEqual(reads, 1);
+}
+
async function testFromSyncSourceErrors() {
// An error from the source does not close it.
let log = [];
@@ -900,6 +972,7 @@ Promise.all([
testFromReturnAndThrowBeforeStart(),
testFromReturnAndThrowCloseSource(),
testFromSyncSourceBatching(),
+ testFromSyncSourceLargeAndEmptyBatches(),
testFromSyncSourceErrors(),
testFromSyncSourceReturnAndThrow(),
testFromSyncSourceQueuesBehindReturn(),