Commit 03f1b405429 for nodejs
commit 03f1b40542959acbb6baa6879047196e081f9839
Author: James M Snell <jasnell@gmail.com>
Date: Wed Oct 7 12:35:30 2026 +0000
stream: read stream/iter share() sync sources at once
A share() consumer that needed the next batch of the source always
waited for an asynchronous read of it, also when the source was a sync
iterable that from() can read synchronously, and every such read added
a reaction to clear the consumer's pending read when it settled.
When there is room in the buffer and no read of the source is pending,
read a batch of a sync source synchronously, with from()'s
kNextSyncBatch, as pipeTo() does: the consumer then gets it at once.
Values that from() normalizes asynchronously are still read
asynchronously. A read waiting for the source now clears itself from
the consumer's pending read when it settles, without a reaction of its
own; only next() calls queued behind another still add one.
With two consumers of a share of a sync source, one 16-byte chunk per
batch, reading is about 2.4 times faster, on par with tee() of a
ReadableStream, with 60% less allocated per chunk. For an async source
it is about 7% faster.
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/share.js b/lib/internal/streams/iter/share.js
index ba457e9023c..57e0885b2ea 100644
--- a/lib/internal/streams/iter/share.js
+++ b/lib/internal/streams/iter/share.js
@@ -30,6 +30,7 @@ const {
fromSync,
isAsyncIterable,
isSyncIterable,
+ kNextSyncBatch,
} = require('internal/streams/iter/from');
const {
@@ -78,6 +79,15 @@ const kNoShareError = Symbol('kNoShareError');
const kPull = Symbol('kPull');
const kSetFactorySignal = Symbol('kSetFactorySignal');
+// Clear `pending` from the pendingNext of the consumer `state` when it
+// settles, unless a next() has been queued behind it.
+function clearPendingNext(state, pending) {
+ const onSettled = () => {
+ if (state.pendingNext === pending) state.pendingNext = null;
+ };
+ PromisePrototypeThen(pending, onSettled, onSettled);
+}
+
class ShareImpl {
#source;
#options;
@@ -160,6 +170,8 @@ class ShareImpl {
waiting: false,
// Created by #readAfterPull() on first use.
afterPull: undefined,
+ // The read #readAfterPull() returned, while it is pending.
+ waitingRead: null,
// The last pending next() of the consumer, if it is waiting for the
// source: the next one waits for it, as next() calls of an async
// generator do.
@@ -186,18 +198,19 @@ class ShareImpl {
let result;
try {
result = self.#tryRead(state);
+ // A sync source can be read at once, when there is room.
+ while (result === kPull &&
+ self.#bufferedBytes < self.#options.budget &&
+ self.#pullSync()) {
+ result = self.#tryRead(state);
+ }
} catch (error) {
return PromiseReject(error);
}
if (result !== kPull) return PromiseResolve(result);
return self.#readAsync(state);
};
- const clearPending = (pending) => {
- const onSettled = () => {
- if (state.pendingNext === pending) state.pendingNext = null;
- };
- PromisePrototypeThen(pending, onSettled, onSettled);
- };
+ const clearPending = (pending) => clearPendingNext(state, pending);
return ObjectSetPrototypeOf({
next() {
@@ -212,7 +225,9 @@ class ShareImpl {
}
state.pendingNext = next;
markPromiseAsHandled(next);
- clearPending(next);
+ // A read waiting for a pull of the source clears pendingNext
+ // itself (see #readAfterPull()).
+ if (next !== state.waitingRead) clearPending(next);
return next;
},
@@ -344,7 +359,9 @@ class ShareImpl {
#readAsync(state) {
state.waiting = true;
if (this.#bufferedBytes < this.#options.budget) {
- return this.#readAfterPull(state);
+ const read = this.#readAfterPull(state);
+ state.waitingRead = read;
+ return read;
}
return this.#readAsyncLoop(state);
}
@@ -386,14 +403,69 @@ class ShareImpl {
// The common case of #readAsyncLoop(), without an async function: there
// is room in the buffer, so read the source and then the consumer's batch.
+ // When the read settles with the result afterPull() returns, it is no
+ // longer pending: clear it from pendingNext, unless a next() has been
+ // queued behind it, without a reaction of its own.
#readAfterPull(state) {
state.afterPull ??= () => {
- const result = this.#tryRead(state);
- return result !== kPull ? result : this.#readAsyncLoop(state);
+ let result;
+ try {
+ result = this.#tryRead(state);
+ } catch (error) {
+ this.#clearWaitingRead(state);
+ throw error;
+ }
+ if (result === kPull) {
+ // Still pending: clear it when it settles.
+ const read = state.waitingRead;
+ state.waitingRead = null;
+ if (state.pendingNext === read) clearPendingNext(state, read);
+ return this.#readAsyncLoop(state);
+ }
+ this.#clearWaitingRead(state);
+ return result;
};
return PromisePrototypeThen(this.#pullFromSource(false), state.afterPull);
}
+ #clearWaitingRead(state) {
+ if (state.pendingNext === state.waitingRead) state.pendingNext = null;
+ state.waitingRead = null;
+ }
+
+ // Read a batch of the source synchronously, if it can be read so (a sync
+ // source normalized by from()) and no read of it is pending. Returns
+ // whether the source was read: a batch buffered, or its end or error
+ // recorded.
+ #pullSync() {
+ if (this.#pulling || this.#sourceExhausted || this.#cancelled) {
+ return false;
+ }
+ try {
+ const iterator = this.#getSourceIterator();
+ const nextSyncBatch = iterator[kNextSyncBatch];
+ if (nextSyncBatch === undefined) return false;
+ const batch = FunctionPrototypeCall(nextSyncBatch, iterator);
+ if (batch === undefined) return false;
+ if (batch === null) {
+ this.#sourceExhausted = true;
+ } else {
+ this.#bufferBatch(batch);
+ }
+ } catch (error) {
+ this.#sourceError = error;
+ this.#sourceExhausted = true;
+ }
+ if (this.#sourceExhausted && this.#consumers.size === 0) {
+ this.#cleanupFactorySignal();
+ }
+ for (let i = 0; i < this.#pullWaiters.length; i++) {
+ this.#pullWaiters[i]();
+ }
+ this.#pullWaiters = [];
+ return true;
+ }
+
async #waitForBufferSpace() {
while (this.#bufferedBytes >= this.#options.budget) {
if (this.#cancelled ||
@@ -461,29 +533,7 @@ class ShareImpl {
let next;
try {
- if (!this.#sourceIterator) {
- if (isAsyncIterable(this.#source)) {
- this.#sourceIterator =
- this.#source[SymbolAsyncIterator]();
- } else if (isSyncIterable(this.#source)) {
- const syncIterator =
- this.#source[SymbolIterator]();
- this.#sourceIterator = ObjectSetPrototypeOf({
- // Its result is passed to PromiseResolve().
- next() {
- return syncIterator.next();
- },
- async return() {
- return syncIterator.return?.() ??
- new IterResult(true, undefined);
- },
- }, null);
- } else {
- throw new ERR_INVALID_ARG_TYPE(
- 'source', ['AsyncIterable', 'Iterable'], this.#source);
- }
- }
- next = this.#sourceIterator.next();
+ next = this.#getSourceIterator().next();
} catch (error) {
this.#onReadError(error);
return promise;
@@ -493,6 +543,32 @@ class ShareImpl {
return promise;
}
+ #getSourceIterator() {
+ if (!this.#sourceIterator) {
+ if (isAsyncIterable(this.#source)) {
+ this.#sourceIterator =
+ this.#source[SymbolAsyncIterator]();
+ } else if (isSyncIterable(this.#source)) {
+ const syncIterator =
+ this.#source[SymbolIterator]();
+ this.#sourceIterator = ObjectSetPrototypeOf({
+ // Its result is passed to PromiseResolve().
+ next() {
+ return syncIterator.next();
+ },
+ async return() {
+ return syncIterator.return?.() ??
+ new IterResult(true, undefined);
+ },
+ }, null);
+ } else {
+ throw new ERR_INVALID_ARG_TYPE(
+ 'source', ['AsyncIterable', 'Iterable'], this.#source);
+ }
+ }
+ return this.#sourceIterator;
+ }
+
// The handlers of a read of the source, created once per share. A read
// ended by a cancellation is ignored.
#onReadResult = (result) => {
diff --git a/test/parallel/test-stream-iter-share-async.js b/test/parallel/test-stream-iter-share-async.js
index 8ea06427543..11df7c9bfa5 100644
--- a/test/parallel/test-stream-iter-share-async.js
+++ b/test/parallel/test-stream-iter-share-async.js
@@ -507,6 +507,57 @@ async function testShareConsumerConcurrentNextCalls() {
assert.strictEqual(dec.decode(r2.value[0]), 'second');
}
+// A sync source is read as the consumers pull, including values that are
+// normalized asynchronously, and its errors reach every consumer after the
+// data before them.
+async function testShareSyncSource() {
+ const reason = new Error('sync source boom');
+ function* source() {
+ yield [Uint8Array.of(1)];
+ yield Promise.resolve(Uint8Array.of(2));
+ yield 'c';
+ yield [Uint8Array.of(4)];
+ throw reason;
+ }
+ const shared = share(source());
+ const consumers = [shared.pull(), shared.pull()];
+ const read = async (consumer) => {
+ const values = [];
+ try {
+ for await (const batch of consumer) values.push(...batch.map((c) => c[0]));
+ } catch (error) {
+ values.push(error);
+ }
+ return values;
+ };
+ const results = await Promise.all(consumers.map(read));
+ for (const values of results) {
+ assert.deepStrictEqual(values, [1, 2, 99, 4, reason]);
+ }
+
+ // Concurrent next() calls get the batches in order.
+ function* numbers() {
+ for (let i = 0; i < 4; i++) yield [Uint8Array.of(i)];
+ }
+ const it = share(numbers()).pull()[Symbol.asyncIterator]();
+ const all = await Promise.all([it.next(), it.next(), it.next(), it.next(),
+ it.next()]);
+ assert.deepStrictEqual(all.map((r) => (r.done ? 'done' : r.value[0][0])),
+ [0, 1, 2, 3, 'done']);
+
+ // 'strict' backpressure rejects a consumer that would exceed the budget
+ // when another one lags.
+ function* big() {
+ for (let i = 0; i < 4; i++) yield [new Uint8Array(8)];
+ }
+ const strict = share(big(), { budget: 16 });
+ const fast = strict.pull()[Symbol.asyncIterator]();
+ strict.pull();
+ await fast.next();
+ await fast.next();
+ await assert.rejects(fast.next(), { code: 'ERR_OUT_OF_RANGE' });
+}
+
// share() accepts string source directly (normalized via from())
async function testShareStringSource() {
const shared = share('hello-share');
@@ -516,6 +567,7 @@ async function testShareStringSource() {
Promise.all([
testBasicShare(),
+ testShareSyncSource(),
testShareMultipleConsumers(),
testShareConsumerCount(),
testShareCancel(),