Commit 6db0cfca0dc for nodejs
commit 6db0cfca0dc33c3eb02af258bea3be3d8f4b1a0b
Author: James M Snell <jasnell@gmail.com>
Date: Wed Oct 7 02:45:17 2026 +0000
stream: create stream/iter transform signals and options lazily
A pull() pipeline with transforms creates an AbortController for the
signal passed to its transforms, and each call of a stateless transform
is passed a new options object holding it. Most transforms never read
the signal, and a new options object for every call allocates on every
batch unless the call is inlined.
Keep the abort state of a pipeline in a PipelineAbort, which creates the
AbortController when the signal is first read, already aborted with the
same reason if the pipeline has been aborted; nothing can have listened
to the signal before, so this cannot be told apart from a signal created
with the pipeline. Code in the pipeline checks the abort state instead
of reading the signal.
Give each transform of a pipeline one options object, passed to every
call of a stateless transform. A transform still cannot change the
options another transform sees. `signal` is an accessor until it is
first read or assigned, after which it is a data property.
This departs from the specification, where TransformCallbackOptions is
a dictionary, converted to a new object with a `signal` data property
for every call.
Calling four stateless transforms that do not read the signal over a
sync source of 16-byte chunks, one per batch, is about 4% faster, and
about 9% faster when the transforms are not inlined.
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/doc/api/stream_iter.md b/doc/api/stream_iter.md
index b8fac507cba..5cc71c47c90 100644
--- a/doc/api/stream_iter.md
+++ b/doc/api/stream_iter.md
@@ -144,10 +144,13 @@ Both forms receive an `options` parameter with the following property:
can check `signal.aborted` or listen for the `'abort'` event to perform
early cleanup.
-In `pull()`, stateless transforms receive a new `options` object for every
-call, and stateful transforms one for the pipeline, so a transform can modify
-its `options` without affecting other transforms. The object does not inherit
-from `Object.prototype`. Transforms passed to [`pullSync()`][] receive no
+Each transform of a pipeline receives its own `options` object, the same one
+for every call of a stateless transform, so a transform can modify its
+`options` without affecting other transforms. The object does not inherit
+from `Object.prototype`. The signal is created when `options.signal` is
+first read, so a pipeline whose transforms never read it does not create one;
+until then, `signal` is an accessor property. It is the same signal for every
+transform of the pipeline. Transforms passed to [`pullSync()`][] receive no
`options`.
The flush signal (`null`) is sent after the source ends, giving transforms
diff --git a/lib/internal/streams/iter/pull.js b/lib/internal/streams/iter/pull.js
index 31bd3acf26a..1cb0276fc87 100644
--- a/lib/internal/streams/iter/pull.js
+++ b/lib/internal/streams/iter/pull.js
@@ -58,6 +58,7 @@ const {
const {
IterResult,
+ PipelineAbort,
kActive,
kDone,
kNullOnceOption,
@@ -581,19 +582,53 @@ function* createSyncPipeline(source, transforms) {
// Async Pipeline Implementation
// =============================================================================
-// The options object passed to async transforms. Stateless transforms get a
-// new one for every call, so it is constructed rather than created as a
-// `{ __proto__: null, signal }` literal (a dictionary-mode object). The
-// prototype is frozen and has no %Object.prototype% in its chain, and the
-// non-enumerable `constructor` lets util.inspect() print the options as
-// `TransformOptions { signal }`.
-function TransformOptions(signal) {
- this.signal = signal;
+// The options object passed to an async transform: one for each transform of
+// a pipeline, passed to every call of a stateless transform. Its `signal` is
+// the pipeline's signal, created by `abort` when first read (see
+// PipelineAbort): until then it is an accessor, which replaces itself with a
+// data property holding the signal. The prototype is frozen and has no
+// %Object.prototype% in its chain, and the non-enumerable `constructor` lets
+// util.inspect() print the options as `TransformOptions { signal }`.
+function TransformOptions(abort) {
+ ObjectDefineProperty(this, 'signal', {
+ __proto__: null,
+ configurable: true,
+ enumerable: true,
+ get() {
+ const signal = abort.signal;
+ ObjectDefineProperty(this, 'signal', {
+ __proto__: null,
+ configurable: true,
+ enumerable: true,
+ value: signal,
+ writable: true,
+ });
+ return signal;
+ },
+ set(value) {
+ ObjectDefineProperty(this, 'signal', {
+ __proto__: null,
+ configurable: true,
+ enumerable: true,
+ value,
+ writable: true,
+ });
+ },
+ });
}
TransformOptions.prototype = ObjectFreeze(ObjectDefineProperty(
{ __proto__: null }, 'constructor',
{ __proto__: null, value: TransformOptions }));
+// The options for each function of a fused run of stateless transforms.
+function createRunOptions(run, abort) {
+ const options = [];
+ for (let i = 0; i < run.length; i++) {
+ options[i] = new TransformOptions(abort);
+ }
+ return options;
+}
+
/**
* Close an async iterator as for await does: for a throw completion
* (`quiet`), wait for it but ignore errors; otherwise reject on errors and
@@ -650,13 +685,13 @@ async function* yieldFusedStatelessOutput(current) {
* @param {Array<Function>} run
* @param {number} index
* @param {any} result - The result of `run[index]`
- * @param {AbortSignal} signal
+ * @param {TransformOptions[]} runOptions - The options of each function
* @yields {Uint8Array[]}
*/
-async function* continueFusedStatelessBatch(run, index, result, signal) {
+async function* continueFusedStatelessBatch(run, index, result, runOptions) {
let current;
for (let i = index; i < run.length; i++) {
- if (i !== index) result = run[i](current, new TransformOptions(signal));
+ if (i !== index) result = run[i](current, runOptions[i]);
if (isPromise(result)) result = await result;
if (result === null) return;
if (i === run.length - 1) {
@@ -680,24 +715,24 @@ async function* continueFusedStatelessBatch(run, index, result, signal) {
* flush each transform after all upstream data, including data emitted by
* earlier flushes, has been processed by that transform.
* @param {Array<Function>} run
- * @param {AbortSignal} signal
+ * @param {TransformOptions[]} runOptions - The options of each function
* @yields {Uint8Array[]}
*/
-async function* flushFusedStatelessAsyncTransforms(run, signal) {
+async function* flushFusedStatelessAsyncTransforms(run, runOptions) {
let pending = [];
for (let i = 0; i < run.length; i++) {
const next = [];
for (let j = 0; j < pending.length; j++) {
const pendingResult = appendTransformResultAsync(
next,
- run[i](pending[j], new TransformOptions(signal)));
+ run[i](pending[j], runOptions[i]));
if (pendingResult !== undefined) {
await pendingResult;
}
}
const flushResult = appendTransformResultAsync(
next,
- run[i](null, new TransformOptions(signal)));
+ run[i](null, runOptions[i]));
if (flushResult !== undefined) {
await flushResult;
}
@@ -731,15 +766,14 @@ const kDelegated = Symbol('kDelegated');
* if any, and close the source unless it has ended; return() propagates
* errors from closing it, throw() ignores them.
*
- * INVARIANT: This function accepts a signal, NOT a pre-built options object.
- * A fresh TransformOptions object is created for each
- * transform invocation to prevent cross-transform mutation.
+ * Each function of the run is passed its own options object on every call.
* @param {AsyncIterable<Uint8Array[]>} source
* @param {Array<Function>} run - Array of stateless transform functions
- * @param {AbortSignal} signal - The pipeline's abort signal
+ * @param {PipelineAbort} abort - The pipeline's abort state
* @returns {AsyncIterator<Uint8Array[]>}
*/
-function applyFusedStatelessAsyncTransforms(source, run, signal) {
+function applyFusedStatelessAsyncTransforms(source, run, abort) {
+ const runOptions = createRunOptions(run, abort);
let state = kStart;
let iterator;
let nextMethod;
@@ -792,9 +826,9 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
function applyBatch(chunks) {
let current = chunks;
for (let i = 0; i < run.length; i++) {
- const result = run[i](current, new TransformOptions(signal));
+ const result = run[i](current, runOptions[i]);
if (isPromise(result)) {
- delegate = continueFusedStatelessBatch(run, i, result, signal);
+ delegate = continueFusedStatelessBatch(run, i, result, runOptions);
return kDelegated;
}
if (result === null) return null;
@@ -804,7 +838,7 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
}
current = normalizeTransformResultFast(result);
if (current === undefined) {
- delegate = continueFusedStatelessBatch(run, i, result, signal);
+ delegate = continueFusedStatelessBatch(run, i, result, runOptions);
return kDelegated;
}
if (current === null) return null;
@@ -832,7 +866,7 @@ function applyFusedStatelessAsyncTransforms(source, run, signal) {
}
if (result.done) {
sourceDone = true;
- delegate = flushFusedStatelessAsyncTransforms(run, signal);
+ delegate = flushFusedStatelessAsyncTransforms(run, runOptions);
return pullDelegate();
}
value = result.value;
@@ -988,7 +1022,7 @@ async function* applyStatefulAsyncTransform(
* @yields {Uint8Array[]}
*/
async function* applyValidatedStatefulAsyncTransform(
- source, transform, receiver, options) {
+ source, transform, receiver, options, abort) {
const output = FunctionPrototypeCall(
transform, receiver, source, options);
for await (const batch of output) {
@@ -999,7 +1033,7 @@ async function* applyValidatedStatefulAsyncTransform(
// Check abort after the transform completes - without the
// withFlushAsync wrapper there is no extra yield to give
// the outer pipeline a chance to see the abort.
- options.signal?.throwIfAborted();
+ abort.throwIfAborted();
}
/**
@@ -1076,22 +1110,17 @@ async function* yieldFrom(source) {
* Build the chain of transform layers of a pipeline.
* @param {AsyncIterable<Uint8Array[]>} normalized
* @param {Array} transforms
- * @param {AbortSignal} transformSignal
+ * @param {PipelineAbort} abort - The pipeline's abort state
* @returns {AsyncIterable<Uint8Array[]>}
*/
-function createAsyncTransformLayers(normalized, transforms, transformSignal) {
+function createAsyncTransformLayers(normalized, transforms, abort) {
// Apply transforms - fuse consecutive stateless transforms into a single
// layer to avoid unnecessary async ticks.
//
- // INVARIANT: Each transform invocation MUST receive its own fresh options
- // object (new TransformOptions(signal)). Transforms may mutate the options
- // object, so sharing a single object across invocations would allow one
- // transform to corrupt the options seen by another. The signal is shared
- // across calls (mutations to it are acceptable), but the containing options
- // object must be unique per call. This is enforced inside
- // applyFusedStatelessAsyncTransforms and applyStatefulAsyncTransform, which
- // accept the signal directly and create the options object per invocation.
- // DO NOT pass a pre-built options object.
+ // Each transform gets its own options object, created here once and passed
+ // to every call of the transform: transforms may mutate the options
+ // object, and must not be able to change the options another transform
+ // sees.
let current = normalized;
let statelessRun = [];
@@ -1101,13 +1130,13 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
// Flush any accumulated stateless run before the stateful transform
if (statelessRun.length > 0) {
current = applyFusedStatelessAsyncTransforms(current, statelessRun,
- transformSignal);
+ abort);
statelessRun = [];
}
- const opts = new TransformOptions(transformSignal);
+ const opts = new TransformOptions(abort);
if (transform[kValidatedTransform]) {
current = applyValidatedStatefulAsyncTransform(
- current, transform.transform, transform.receiver, opts);
+ current, transform.transform, transform.receiver, opts, abort);
} else {
current = applyStatefulAsyncTransform(
current, transform.transform, transform.receiver, opts);
@@ -1119,7 +1148,7 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
// Flush remaining stateless run
if (statelessRun.length > 0) {
current = applyFusedStatelessAsyncTransforms(current, statelessRun,
- transformSignal);
+ abort);
}
return current;
}
@@ -1130,9 +1159,9 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
* layer for every batch (see applyFusedStatelessAsyncTransforms()).
*
* When started by the first next(), it checks `signal`, then creates the
- * controller whose signal the transforms get, aborted when `signal` aborts.
- * Each batch, and the end, is passed on only if the transforms' signal has
- * not been aborted. If the pipeline fails, the transforms' signal is aborted
+ * abort state whose signal the transforms get, aborted when `signal` aborts.
+ * Each batch, and the end, is passed on only if the pipeline has not been
+ * aborted. If the pipeline fails, the transforms' signal is aborted
* with the error; if it is stopped early by return() or throw(), the
* transforms are closed and their signal is aborted.
* @param {AsyncIterable<Uint8Array[]>} source
@@ -1142,7 +1171,7 @@ function createAsyncTransformLayers(normalized, transforms, transformSignal) {
*/
function createAsyncTransformPipeline(source, transforms, signal) {
let state = kStart;
- let controller;
+ let abort;
let abortHandler;
let completed = false;
let iterator;
@@ -1151,10 +1180,10 @@ function createAsyncTransformPipeline(source, transforms, signal) {
// What an async generator would do in its `finally` block.
function cleanup() {
- if (!completed && !controller.signal.aborted) {
+ if (!completed && !abort.aborted) {
// Consumer stopped early or return() was called.
// If a transform listener throws here, let it propagate.
- controller.abort(lazyDOMException('Aborted', 'AbortError'));
+ abort.abort(lazyDOMException('Aborted', 'AbortError'));
}
// Clean up user signal listener to prevent holding controller alive
if (signal && abortHandler) {
@@ -1182,9 +1211,7 @@ function createAsyncTransformPipeline(source, transforms, signal) {
state = kDone;
try {
try {
- if (!controller.signal.aborted) {
- abortSignal(controller.signal, error);
- }
+ abort.abort(error);
} finally {
cleanup();
}
@@ -1206,7 +1233,7 @@ function createAsyncTransformPipeline(source, transforms, signal) {
// A transform can abort while completing without producing a final
// batch, for example when an async flush resolves to null. In that
// case there is no batch with which to observe the abort.
- controller.signal.throwIfAborted();
+ abort.throwIfAborted();
completed = true;
return complete(new IterResult(true, undefined));
}
@@ -1214,9 +1241,8 @@ function createAsyncTransformPipeline(source, transforms, signal) {
} catch (error) {
return fail(error);
}
- try {
- controller.signal.throwIfAborted();
- } catch (error) {
+ if (abort.aborted) {
+ const error = abort.reason;
// Like for await when its body throws: close the transforms first.
return PromisePrototypeThen(
closeAsyncIterator(iterator, true), () => fail(error));
@@ -1249,17 +1275,16 @@ function createAsyncTransformPipeline(source, transforms, signal) {
}
state = kActive;
const normalized = yieldAbortable(source, signal);
- // Create internal controller for transform cancellation.
- controller = new AbortController();
+ abort = new PipelineAbort();
if (signal) {
abortHandler = () => {
- abortSignal(controller.signal, signal.reason);
+ abort.abort(signal.reason);
};
signal.addEventListener('abort', abortHandler, kNullOnceOption);
}
try {
const current = createAsyncTransformLayers(
- normalized, transforms, controller.signal);
+ normalized, transforms, abort);
iterator = current[SymbolAsyncIterator]();
nextMethod = iterator.next;
} catch (error) {
diff --git a/lib/internal/streams/iter/utils.js b/lib/internal/streams/iter/utils.js
index 6b40f5a2903..b4eb5e9c662 100644
--- a/lib/internal/streams/iter/utils.js
+++ b/lib/internal/streams/iter/utils.js
@@ -37,6 +37,10 @@ const {
const { isSharedArrayBuffer, isUint8Array } = require('internal/util/types');
const { kWeakHandler } = require('internal/event_target');
+const {
+ AbortController,
+ abortSignal,
+} = require('internal/abort_controller');
const { RingBuffer } = require('internal/streams/iter/ringbuffer');
const {
@@ -110,6 +114,50 @@ function onSignalAbort(signal, handler) {
}
}
+/**
+ * The abort state of a pipeline: what the AbortController of a pipeline in
+ * the specification holds, without creating an AbortController unless its
+ * signal is used. Most transforms never read the signal passed to them, so
+ * most pipelines never need one. When the signal is first read, it is
+ * created aborted with the same reason if the pipeline has been aborted:
+ * nothing can have listened to it before, so this cannot be told apart from
+ * a signal created with the pipeline. Code inside the pipeline checks
+ * `aborted` instead of reading the signal.
+ */
+class PipelineAbort {
+ aborted = false;
+ reason = undefined;
+ #controller = null;
+
+ get signal() {
+ let controller = this.#controller;
+ if (controller === null) {
+ controller = this.#controller = new AbortController();
+ if (this.aborted) abortSignal(controller.signal, this.reason);
+ }
+ return controller.signal;
+ }
+
+ /**
+ * Abort the pipeline with `reason`, if it is not aborted already. Abort
+ * listeners on the signal, if it has been created, run synchronously, and
+ * errors they throw propagate.
+ * @param {any} reason
+ */
+ abort(reason) {
+ if (this.aborted) return;
+ this.aborted = true;
+ this.reason = reason;
+ if (this.#controller !== null) {
+ abortSignal(this.#controller.signal, reason);
+ }
+ }
+
+ throwIfAborted() {
+ if (this.aborted) throw this.reason;
+ }
+}
+
/**
* Wrap an async source so each pending read is abort-aware.
* @param {AsyncIterable<Uint8Array[]>} source - The source to read from.
@@ -942,6 +990,7 @@ module.exports = {
kStart,
PendingRequest,
PendingWrite,
+ PipelineAbort,
kMultiConsumerDefaultBudget,
kNullOnceOption,
kPushDefaultBudget,
diff --git a/test/parallel/test-stream-iter-pull-async.js b/test/parallel/test-stream-iter-pull-async.js
index 308e3a0ebb9..4c1bc0a7a14 100644
--- a/test/parallel/test-stream-iter-pull-async.js
+++ b/test/parallel/test-stream-iter-pull-async.js
@@ -553,7 +553,7 @@ async function testPipeToStringSource() {
assert.strictEqual(data, 'hello-pipe');
}
-// INVARIANT: Each transform invocation receives its own options object.
+// Each transform receives its own options object.
// A transform that mutates options must not affect subsequent transforms.
async function testTransformOptionsNotShared() {
const seen = [];
@@ -575,41 +575,97 @@ async function testTransformOptionsNotShared() {
assert.strictEqual(seen[1].mutated, undefined);
}
-// Stateless transforms get a new options object for every call, and stateful
-// transforms one for the pipeline. The options object has only `signal`, does
+// Each transform of a pipeline gets its own options object, passed to every
+// call of a stateless transform. The options object has only `signal`, does
// not inherit from Object.prototype, and its prototype is frozen, so that a
-// transform cannot pass state to others through it.
+// transform cannot pass state to others through it. The signal is the same
+// for every transform and every call.
async function testTransformOptionsShape() {
const seen = [];
+ const statelessSeen = [];
+ let statefulOptions;
const stateless = (chunks, options) => {
seen.push(options);
+ statelessSeen.push(options);
return chunks;
};
const stateful = {
async* transform(source, options) {
seen.push(options);
+ statefulOptions = options;
for await (const chunks of source) yield chunks;
},
};
const ac = new AbortController();
await text(pull(from(['a', 'b']), stateless, stateful,
{ signal: ac.signal }));
- // Stateless: one call per batch plus the flush call.
+ // Stateless: one call per batch plus the flush call; stateful: one call.
+ assert.strictEqual(statelessSeen.length, 3);
+ assert.strictEqual(new Set(statelessSeen).size, 1);
assert.strictEqual(seen.length, 4);
- assert.strictEqual(new Set(seen).size, seen.length);
+ assert.notStrictEqual(statefulOptions, statelessSeen[0]);
for (const options of seen) {
assert.strictEqual(options instanceof Object, false);
assert.deepStrictEqual(Object.keys(options), ['signal']);
assert.ok(options.signal instanceof AbortSignal);
+ assert.strictEqual(options.signal, seen[0].signal);
assert.strictEqual(Object.isFrozen(Object.getPrototypeOf(options)), true);
assert.match(inspect(options), /^TransformOptions \{ signal: /);
}
- assert.strictEqual(Object.getPrototypeOf(seen[0]),
- Object.getPrototypeOf(seen[3]));
+ assert.strictEqual(Object.getPrototypeOf(statefulOptions),
+ Object.getPrototypeOf(statelessSeen[0]));
assert.throws(() => { Object.getPrototypeOf(seen[0]).leak = true; },
TypeError);
}
+// `options.signal` can be assigned, as a data property could, whether or
+// not it has been read.
+async function testTransformOptionsSignalAssignable() {
+ const seen = [];
+ let calls = 0;
+ const transform = (chunks, options) => {
+ seen.push(options.signal);
+ options.signal = ++calls;
+ return chunks;
+ };
+ const unread = (chunks, options) => {
+ options.signal = 'unread';
+ seen.push(options.signal);
+ return chunks;
+ };
+ await text(pull(from(['a', 'b']), transform, unread));
+ assert.ok(seen[0] instanceof AbortSignal);
+ assert.deepStrictEqual(seen.slice(1), ['unread', 1, 'unread', 2, 'unread']);
+}
+
+// The transforms' signal is the pipeline's: first read after the pipeline
+// has been aborted, it is already aborted with the same reason, and read
+// before, it is aborted when the pipeline is.
+async function testTransformSignalReadAfterAbort() {
+ const reason = new Error('stop');
+ let options;
+ const transform = (chunks, opts) => {
+ options = opts;
+ throw reason;
+ };
+ await assert.rejects(text(pull(from('a'), transform)), reason);
+ assert.strictEqual(options.signal.aborted, true);
+ assert.strictEqual(options.signal.reason, reason);
+ assert.strictEqual(options.signal, options.signal);
+
+ const ac = new AbortController();
+ let signal;
+ const iterator = pull(from(['a', 'b']), (chunks, opts) => {
+ signal ??= opts.signal;
+ return chunks;
+ }, { signal: ac.signal })[Symbol.asyncIterator]();
+ await iterator.next();
+ assert.strictEqual(signal.aborted, false);
+ ac.abort(reason);
+ assert.strictEqual(signal.aborted, true);
+ assert.strictEqual(signal.reason, reason);
+}
+
// Run the uncaughtException test sequentially (it installs a global handler
// that would interfere with concurrent tests).
// Transform pipelines read and close the source like an async generator
@@ -760,6 +816,8 @@ async function testTransformReturnClosesOutputAndSource() {
testPipeToStringSource(),
testTransformOptionsNotShared(),
testTransformOptionsShape(),
+ testTransformSignalReadAfterAbort(),
+ testTransformOptionsSignalAssignable(),
testTransformErrorClosesSource(),
testTransformSourceErrorDoesNotCloseSource(),
testPipeToTransformsStoppedEarly(),