@nxtedition/scheduler 4.1.11 → 4.1.13

package/lib/scheduler.js

@@ -1,3 +1,4 @@
+import { types } from 'node:util';
 import { FastQueue, parsePriority, Queue } from "./queue.js";
 // Layout of the 128-byte (32 × Int32) shared state buffer:
 //
@@ -12,11 +13,23 @@ import { FastQueue, parsePriority, Queue } from "./queue.js";
 // loads WAITERS to decide whether to skip Atomics.notify does NOT invalidate
 // the cache line carrying RUNNING — under N-way contention that would
 // penalize every concurrent acquirer on every release.
+//
+// (An earlier revision sharded RUNNING/WAITERS across cache lines + a separate
+// futex word. Benchmarking on the x64 target showed it was a net regression:
+// RUNNING is read on every acquire, so aggregating shards costs more coherency
+// traffic than the single-line write contention it avoids. Reverted to one
+// counter; the futex is RUNNING itself, which makes waitAsync self-correcting.)
 const RUNNING_INDEX = 0;
 const MAGIC_INDEX = 8;
 const CONCURRENCY_INDEX = 16;
 const WAITERS_INDEX = 24;
 const SCHEDULER_MAGIC = 0x5ca4edde; // sanity-check sentinel written by makeSharedState
+// CONCURRENCY is stored in an Int32 slot. A finite value above this would silently
+// wrap on store (2**31 → -2147483648 → "unlimited", 2**32 → 0 → permanent hang), so
+// values that don't fit are either rejected (makeSharedState) or reported as
+// Infinity by the `concurrency` getter (non-shared mode, where the real limit is
+// still enforced via #limits/#max as ordinary numbers).
+const MAX_INT32 = 0x7fffffff;
 // Per-priority limit keys, ordered to match `Queue.queues` (lowest=0, normal=3, highest=6).
 const PRIORITY_KEYS = ['lowest', 'lower', 'low', 'normal', 'high', 'higher', 'highest'];
 // Reject anything that isn't a literal config object — Map/Date/Array/class instances all
@@ -123,6 +136,28 @@ export class Scheduler extends Queue {
     // bypasses per-priority limits to prevent starvation — without this hard cap, the
     // bypass could push running above max during drain.
     #max;
+    // ---- child() hierarchy ----
+    // A child Scheduler enforces its OWN (local, per-priority) concurrency cap on top of its
+    // parent's overall `max`: a task dispatched through a child must be admitted by both.
+    // Children delegate all global-capacity accounting (and, when the root is shared, all
+    // cross-thread waiting) up the parent chain via #tryAcquireGlobal / #releaseGlobal, so
+    // only the root ever touches the SharedArrayBuffer. See child().
+    #parent = null;
+    #children = null;
+    // For a node that is itself a child: `running` counts ALL slots this node holds globally
+    // — its own direct tasks PLUS every descendant's (a descendant's #tryAcquireGlobal
+    // increments it up the chain). That total is what this node's hard `#max` and
+    // #tryAcquireGlobal measure. But the node's PER-PRIORITY caps apply only to its OWN
+    // directly-submitted tasks, so those are measured against #directRunning (incremented
+    // solely by this node's own dispatch). For a leaf child the two are equal; they diverge
+    // only for an intermediate node used both as a pool and directly. Unused on the root.
+    #directRunning = 0;
+    // Round-robin start offset across #children, advanced once per dispatch pass so no
+    // sibling can monopolise freed global capacity when the pool is over-subscribed.
+    #driveCursor = 0;
+    // Re-entrancy guard for the hierarchy dispatch loop (#driveLoop), distinct from
+    // `releasing` which guards the non-hierarchy #schedule.
+    #driving = false;
     running = 0;
     pending = 0;
     releasing = false;
@@ -141,7 +176,13 @@ export class Scheduler extends Queue {
         try {
             const result = fn(opaque);
             if (result != null && typeof result.then === 'function') {
-                void result.then(resolve, reject).then(this.release);
+                // Promise.resolve assimilates the thenable: identity for native promises (no
+                // hot-path allocation), and for user thenables it restores the Promises/A+
+                // guarantees raw .then lacks — a then() that returns undefined no longer
+                // TypeErrors the chain, a thenable that calls its callback twice can no
+                // longer double-release the slot, and release is chained off a real promise
+                // instead of whatever object the thenable's then() happened to return.
+                void Promise.resolve(result).then(resolve, reject).then(this.release);
             }
             else {
                 resolve(result);
@@ -157,7 +198,10 @@ export class Scheduler extends Queue {
         if (concurrency === Infinity) {
             concurrency = -1;
         }
-        else if (concurrency == null || !Number.isInteger(concurrency) || concurrency < 0) {
+        else if (concurrency == null ||
+            !Number.isInteger(concurrency) ||
+            concurrency < 0 ||
+            concurrency > MAX_INT32) {
             throw new Error('Invalid concurrency');
         }
         const stateBuffer = new SharedArrayBuffer(128); // 2 cache lines, one per field
@@ -188,7 +232,10 @@ export class Scheduler extends Queue {
         if (options != null && !isPlainObject(options)) {
             throw new Error('Invalid options');
         }
-        if (optsOrArrayBuffer instanceof SharedArrayBuffer) {
+        // util.types.isSharedArrayBuffer instead of instanceof: a SAB from another realm
+        // (vm context, jest sandbox) fails instanceof and would fall into the options
+        // branch with a misleading 'Invalid options' error.
+        if (types.isSharedArrayBuffer(optsOrArrayBuffer)) {
             const state = optsOrArrayBuffer;
             if (state.byteLength !== 128) {
                 throw new Error('Invalid SharedArrayBuffer size');
@@ -216,7 +263,9 @@ export class Scheduler extends Queue {
             const { limits, max } = buildLimits(opts?.concurrency);
             this.stateView = new Int32Array(64);
             // Persist `max` so the public `concurrency` getter still reflects the overall ceiling.
-            Atomics.store(this.stateView, CONCURRENCY_INDEX, max === Number.MAX_SAFE_INTEGER ? -1 : max);
+            // Values that don't fit Int32 are effectively unlimited — report them as Infinity
+            // (-1 sentinel) instead of letting the store wrap to garbage.
+            Atomics.store(this.stateView, CONCURRENCY_INDEX, max > MAX_INT32 ? -1 : max);
             this.shared = false;
             this.#limits = limits;
             this.#max = max;
@@ -253,17 +302,72 @@ export class Scheduler extends Queue {
         // Atomics.sub(WAITERS, 1) in its .then handler would normally pair the
         // increment from #maybeWait — but the .then handler sees dead===true
         // and skips. Drain WAITERS here to keep the cross-thread counter honest.
-        if (this.#waitPromise != null) {
+        if (this.shared && this.#waitPromise != null) {
             Atomics.sub(this.stateView, WAITERS_INDEX, 1);
         }
-        if (released > 0) {
+        if (released > 0 && this.shared) {
             Atomics.sub(this.stateView, RUNNING_INDEX, released);
             if (this.stateView[WAITERS_INDEX] > 0) {
                 Atomics.notify(this.stateView, RUNNING_INDEX, released);
             }
         }
     }
+    /**
+     * Create a child Scheduler that enforces an ADDITIONAL concurrency limit on top of this
+     * (the parent). A task dispatched through the child runs only when it is admitted by BOTH
+     * the child's own per-priority cap (counting the child's running tasks) AND the parent's
+     * overall `max` (counting all tasks in the parent's pool, across workers when the parent
+     * is shared).
+     *
+     * Canonical use: a shared parent caps global concurrency (e.g. 16 reads across the whole
+     * process) while each worker uses a child to cap its local share (e.g. 4):
+     *
+     *   const parent = new Scheduler(Scheduler.makeSharedState(16)) // global pool
+     *   const reads = parent.child({ concurrency: 4 })              // this worker's cap
+     *   await reads.run(() => fs.readFile(path), 'high')
+     *
+     * `opts` mirrors the constructor's options (so per-priority caps work too:
+     * `parent.child({ concurrency: { max: 4, low: 1 } })`); omit it for an unlimited local
+     * cap (only the parent constrains).
+     *
+     * Priorities: the child has its own independent per-priority caps and starvation-
+     * prevention lottery; the parent's overall `max` is the global gate (a SOFT limit when
+     * the parent/root is shared — the same bounded read-then-increment overshoot as a plain
+     * shared Scheduler). The parent's own per-priority caps constrain only tasks submitted
+     * DIRECTLY to the parent — child tasks see the parent solely as an overall `max`.
+     * Children may be nested arbitrarily.
+     */
+    child(opts) {
+        if (this.dead) {
+            throw new Error('Scheduler is disposed');
+        }
+        // A child is always a local (non-shared) Scheduler: it owns no SharedArrayBuffer and
+        // delegates every global-capacity decision to the parent chain. No opts → unlimited
+        // local cap (`{}`), so only the parent constrains. (Pass an explicit `{}` rather than
+        // relying on an optional constructor param, keeping the public constructor signature
+        // unchanged.)
+        const c = new Scheduler(opts ?? {});
+        c.#parent = this;
+        (this.#children ??= []).push(c);
+        return c;
+    }
+    // The root of this hierarchy (itself when not a child). Depth is tiny in practice.
+    #root() {
+        let n = this.#parent;
+        if (n === null) {
+            return this;
+        }
+        while (n.#parent !== null) {
+            n = n.#parent;
+        }
+        return n;
+    }
     run(fn, priority = Queue.NORMAL, opaque) {
+        if (typeof fn !== 'function') {
+            // Validate up front: a queued non-function would otherwise detonate later
+            // inside the dispatch loop, mis-attributed to whoever triggered the drain.
+            throw new Error('Invalid fn');
+        }
         return new Promise((resolve, reject) => {
             // After dispose/exit the scheduler is inert: #tryAcquire returns false and
             // acquire() refuses to queue, so without this guard the returned promise would
@@ -273,10 +377,27 @@ export class Scheduler extends Queue {
                 reject(new Error('Scheduler is disposed'));
                 return;
             }
+            // A hard cap of 0 anywhere in the chain can never dispatch anything (even the
+            // lottery bypass is gated on running < max), so the promise would hang forever.
+            // Fail fast, mirroring the disposed-scheduler rejection above.
+            if (this.#max === 0) {
+                reject(new Error('Scheduler concurrency is 0'));
+                return;
+            }
+            for (let n = this.#parent; n !== null; n = n.#parent) {
+                if (n.#max === 0) {
+                    reject(new Error('Scheduler concurrency is 0'));
+                    return;
+                }
+            }
             const ctx = { resolve, reject, fn, opaque };
             const p = parsePriority(priority);
-            if (this.#tryAcquire(p)) {
-                // Fast path: slot available immediately — call #runTask directly.
+            if (this.queues[p + 3].cnt === 0 && this.#tryAcquire(p)) {
+                // Fast path: nothing queued ahead of us at this priority and a slot is
+                // available immediately — call #runTask directly. The same-priority gate
+                // preserves FIFO within a priority: without it a fresh task could overtake
+                // work queued at the same priority during the (shared-mode) microtask window
+                // between a remote release and the parked waiter's wakeup.
                 this.#runTask(ctx);
             }
             else {
@@ -287,9 +408,30 @@ export class Scheduler extends Queue {
         });
     }
     acquire(fn, priority = Queue.NORMAL, opaque) {
+        if (typeof fn !== 'function') {
+            // Validate up front: a queued non-function would otherwise detonate later
+            // inside the dispatch loop, mis-attributed to whoever triggered the drain.
+            throw new Error('Invalid fn');
+        }
         if (this.dead) {
             return false;
         }
+        // In a child() hierarchy, a hard cap of 0 anywhere in the chain can never dispatch this
+        // work: queuing it would strand the item AND, under a shared root, busy-spin #driveLoop's
+        // lost-race retry (a structurally-dead subtree the loop mistakes for a transient race).
+        // Refuse up front and enqueue nothing. (A plain, non-hierarchy max-0 scheduler keeps its
+        // existing contract of queuing the task — it simply never dispatches; see run(), which
+        // rejects max-0 either way.)
+        if (this.#parent !== null || this.#children !== null) {
+            if (this.#max === 0) {
+                return false;
+            }
+            for (let n = this.#parent; n !== null; n = n.#parent) {
+                if (n.#max === 0) {
+                    return false;
+                }
+            }
+        }
         const p = priority == null ? Queue.NORMAL : parsePriority(priority);
         // Snapshot RUNNING *before* the capacity check. If a remote release lands
         // between a failed #tryAcquire and the Atomics.waitAsync in #maybeWait, its
@@ -300,7 +442,8 @@ export class Scheduler extends Queue {
         // A fresh read taken after the failed check would match the post-release
         // value and park forever on a queue nobody will ever notify.
         const expected = this.shared ? this.stateView[RUNNING_INDEX] : 0;
-        if (this.#tryAcquire(p)) {
+        // Same-priority FIFO gate: see run().
+        if (this.queues[p + 3].cnt === 0 && this.#tryAcquire(p)) {
             try {
                 fn(opaque);
             }
@@ -314,19 +457,40 @@ export class Scheduler extends Queue {
         const queue = this.queues[p + 3];
         queue.arr.push(fn, opaque);
         queue.cnt += 1;
+        if (queue.cnt === 1) {
+            this.nonEmptyMask |= 1 << queue.i;
+        }
         this.pending += 1;
-        if (this.shared) {
-            this.#maybeWait(expected);
+        if (this.#parent !== null || this.#children !== null) {
+            // Part of a child() hierarchy — dispatch (and, for a shared root, parking) is
+            // coordinated from the root across the whole tree.
+            this.#root().#driveLoop();
+        }
+        else if (this.shared) {
+            const fresh = this.#maybeWait(expected);
+            if (fresh !== -1) {
+                this.#schedule(fresh);
+            }
         }
         return false;
     }
+    // Park a waiter on RUNNING when this instance has queued work that only a remote
+    // release can unblock. Returns -1 when parked (or when waiting is not applicable:
+    // non-shared, nothing pending, already parked, cap 0); otherwise returns a fresh
+    // RUNNING value the caller must re-dispatch with (#schedule) instead of parking.
+    //
+    // We park even while local tasks are running: a local release does drive
+    // #schedule directly, but capacity freed by a REMOTE release is only ever
+    // observed through this waiter — refusing to park while this.running > 0 left
+    // the backlog serialized behind the slowest local task (and hung forever behind
+    // an unbounded one) while free shared slots sat idle.
     #maybeWait(expected) {
-        if (!this.shared || this.running > 0 || this.pending === 0 || this.#waitPromise) {
-            return;
+        if (!this.shared || this.pending === 0 || this.#waitPromise) {
+            return -1;
         }
         // No point waiting when global cap is 0 — value can never drop to enable dispatch.
         if (this.#max === 0) {
-            return;
+            return -1;
         }
         // Bump WAITERS BEFORE waitAsync so any concurrent release that already
         // decremented RUNNING will observe us — a release that misses our increment
@@ -335,6 +499,18 @@ export class Scheduler extends Queue {
         // pair the decrement in the .then; the cost is one wasted atomic pair on
         // the rare not-equal path.
         Atomics.add(this.stateView, WAITERS_INDEX, 1);
+        // ABA guard: `expected` predates the caller's failed capacity check. A remote
+        // release in between skipped notify (WAITERS was 0) — and if a remote acquire
+        // then restored RUNNING to exactly `expected`, waitAsync would park on a value
+        // that already changed, with the missed release's capacity unconsumed. Re-read
+        // AFTER the WAITERS increment: from this point any release will notify us, so
+        // an unchanged read is safe to park on, and a changed read means capacity may
+        // be free — hand it back to the caller for a dispatch pass instead of parking.
+        const current = this.stateView[RUNNING_INDEX];
+        if (current !== expected) {
+            Atomics.sub(this.stateView, WAITERS_INDEX, 1);
+            return current;
+        }
         // Atomics.waitAsync does not keep the Node event loop alive on its own. Callers
         // with idle workers (running===0 and tasks queued) need an external keep-alive
         // (their own setTimeout, setInterval, HTTP server, etc.) until notify wakes us.
@@ -342,24 +518,63 @@ export class Scheduler extends Queue {
         this.#waitPromise = (async ? value : Promise.resolve(value)).then(() => {
             // If [kOnExit] already fired (Node still drains the microtask queue
             // after process.on('exit')), it has already drained WAITERS for us and
-            // any further state mutation would corrupt shared counters.
+            // any further state mutation would corrupt shared counters. But we must
+            // forward the wakeup: Atomics.waitAsync cannot be cancelled, so a
+            // disposed instance's waiter stays in the (FIFO) wait set and a
+            // notify(1) aimed at a live waiter parked behind it would otherwise be
+            // swallowed here, stranding that waiter's queue forever. Re-notifying
+            // re-targets the wakeup to the next waiter; when none is parked it is a
+            // harmless no-op.
             if (this.dead) {
+                Atomics.notify(this.stateView, RUNNING_INDEX, 1);
                 return;
             }
             Atomics.sub(this.stateView, WAITERS_INDEX, 1);
             this.#waitPromise = null;
-            this.#schedule(this.stateView[RUNNING_INDEX]);
+            // Re-dispatch via the path matching this instance's CURRENT shape, not the one it had
+            // when it parked: child() may have been called on this (formerly plain) shared
+            // scheduler while it was parked here, turning it into a hierarchy node. Routing
+            // through #schedule would only drain this node's own direct queue and strand the new
+            // subtree work; #driveLoop drives the whole tree. (acquire()/release() pick the
+            // dispatcher the same way.)
+            if (this.#parent !== null || this.#children !== null) {
+                this.#root().#driveLoop();
+            }
+            else {
+                this.#schedule(this.stateView[RUNNING_INDEX]);
+            }
         });
+        return -1;
     }
     tryAcquire(priority) {
         const p = priority == null ? Queue.NORMAL : parsePriority(priority);
-        return this.#tryAcquire(p);
+        // Same-priority FIFO gate (see run()): refuse a slot that work queued at this
+        // priority is already waiting for, mirroring Limiter.tryConsume's pending check.
+        return this.queues[p + 3].cnt === 0 && this.#tryAcquire(p);
     }
     #tryAcquire(priority) {
         if (this.dead) {
             return false;
         }
         const limit = this.#limits[priority + 3];
+        if (this.#parent !== null) {
+            // Child: enforce the local per-priority cap (against this node's own DIRECT running
+            // count, not descendant slots), AND this node's overall #max against its whole subtree
+            // (this.running = direct + descendants). For a leaf the two coincide, but for an
+            // intermediate node whose descendants already hold slots the subtree check is what
+            // keeps a direct task from pushing the node past its own max (#drainSelf gates the
+            // same way). Then take a global slot from the parent chain — the parent's
+            // #tryAcquireGlobal performs the shared Atomics, so the child never does.
+            if (this.#directRunning >= limit || this.running >= this.#max) {
+                return false;
+            }
+            if (!this.#parent.#tryAcquireGlobal()) {
+                return false;
+            }
+            this.#directRunning += 1;
+            this.running += 1;
+            return true;
+        }
         if (this.shared) {
             // We use non-atomic access here as an optimization and treat the concurrency limit as a soft limit.
             if (this.stateView[RUNNING_INDEX] < limit) {
@@ -376,6 +591,55 @@ export class Scheduler extends Queue {
         }
         return false;
     }
+    // Take one slot against this node's overall `max` AND every ancestor's, used by a child
+    // to acquire global capacity. Self is checked first (cheap, no side effect) then the
+    // parent chain; self is only incremented once the whole chain grants, so a denial higher
+    // up never needs a rollback. Returns false if any level is at its cap.
+    #tryAcquireGlobal() {
+        if (this.dead) {
+            return false;
+        }
+        if (this.shared) {
+            if (this.stateView[RUNNING_INDEX] >= this.#max) {
+                return false;
+            }
+        }
+        else if (this.running >= this.#max) {
+            return false;
+        }
+        if (this.#parent !== null && !this.#parent.#tryAcquireGlobal()) {
+            return false;
+        }
+        if (this.shared) {
+            Atomics.add(this.stateView, RUNNING_INDEX, 1);
+        }
+        this.running += 1;
+        return true;
+    }
+    // Mirror of #tryAcquireGlobal's increments: release one slot at this node and every
+    // ancestor, waking parked waiters on each shared level.
+    #releaseGlobal() {
+        // Stop at a dead ancestor (mirrors #tryAcquireGlobal's dead guard and release()'s). At
+        // process exit only the shared ROOT runs [kOnExit] — a local child is not in the global
+        // `schedulers` set, so its dead flag is never set and a late post-exit microtask from an
+        // in-flight child task can still reach here. kOnExit already subtracted this node's held
+        // slots from the SAB; decrementing again would double-count and drive the cross-thread
+        // RUNNING counter negative. (Ancestors above a dead node were balanced by the same
+        // kOnExit, so stopping the whole walk here is correct.)
+        if (this.dead) {
+            return;
+        }
+        this.running -= 1;
+        if (this.shared) {
+            Atomics.sub(this.stateView, RUNNING_INDEX, 1);
+            if (this.stateView[WAITERS_INDEX] > 0) {
+                Atomics.notify(this.stateView, RUNNING_INDEX, 1);
+            }
+        }
+        if (this.#parent !== null) {
+            this.#parent.#releaseGlobal();
+        }
+    }
     #schedule(running) {
         const shared = this.shared;
         if (this.dead || this.pending === 0 || this.releasing) {
@@ -389,13 +653,21 @@ export class Scheduler extends Queue {
                 // Hard cap on global concurrency. getNextQueue's lottery bypasses per-priority
                 // limits to prevent starvation and would otherwise push running above max.
                 if (running >= max) {
-                    this.#maybeWait(running);
-                    break;
+                    // #maybeWait returns a fresh RUNNING value (instead of parking) when the
+                    // counter changed under us — loop back and retry the dispatch with it.
+                    running = this.#maybeWait(running);
+                    if (running === -1) {
+                        break;
+                    }
+                    continue;
                 }
                 const queue = this.getNextQueue(limits, running);
                 if (queue == null) {
-                    this.#maybeWait(running);
-                    break;
+                    running = this.#maybeWait(running);
+                    if (running === -1) {
+                        break;
+                    }
+                    continue;
                 }
                 const fn = queue.arr[queue.idx];
                 queue.arr[queue.idx++] = null;
@@ -403,6 +675,7 @@ export class Scheduler extends Queue {
                 queue.arr[queue.idx++] = null;
                 queue.cnt -= 1;
                 if (queue.cnt === 0) {
+                    this.nonEmptyMask &= ~(1 << queue.i);
                     queue.idx = 0;
                     // `queue.arr = []` is faster than `arr.length = 0` in V8: truncation walks
                     // the elements area to clear refs, while reassigning drops the old backing
@@ -422,10 +695,16 @@ export class Scheduler extends Queue {
                     fn(opaque);
                 }
                 catch (err) {
-                    // Balance the counter we just incremented before propagating. this.releasing=true
-                    // so the nested release() only decrements — it won't re-enter this dispatch loop.
+                    // Balance the counter we just incremented (this.releasing=true keeps the
+                    // nested release() from re-entering this dispatch loop), then isolate the
+                    // failure exactly like Limiter's drain: surface it asynchronously and keep
+                    // dispatching. Propagating from here would abort the loop — and when the
+                    // thrower didn't release a slot first, no future release is coming, so the
+                    // remaining backlog (and any queued run() promises) would strand forever.
                     this.release();
-                    throw err;
+                    queueMicrotask(() => {
+                        throw err;
+                    });
                 }
                 // Re-read running after fn() in case it synchronously called release().
                 // Plain Int32Array load: same soft-limit relaxation as #tryAcquire — a
@@ -440,6 +719,220 @@ export class Scheduler extends Queue {
             this.releasing = false;
         }
     }
+    // ---- hierarchy dispatch (child() schedulers) ----
+    // True if this node or any descendant has queued work.
+    #subtreeHasPending() {
+        if (this.pending > 0) {
+            return true;
+        }
+        const children = this.#children;
+        if (children !== null) {
+            for (let i = 0; i < children.length; i++) {
+                if (children[i].#subtreeHasPending()) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    // Dispatch this node's OWN queued tasks, each gated by its local per-priority cap (with
+    // the starvation lottery) AND a global slot from the parent chain. Returns true if at
+    // least one task was dispatched.
+    #drainSelf() {
+        if (this.dead || this.pending === 0) {
+            return false;
+        }
+        const isRoot = this.#parent === null;
+        let progressed = false;
+        while (this.pending > 0) {
+            // Hard cap on THIS node's whole-subtree concurrency, checked BEFORE getNextQueue
+            // exactly like #schedule: the GLOBAL running total for the root, this node's
+            // `running` (own + descendants) for a child. getNextQueue's starvation lottery
+            // deliberately BYPASSES the per-priority limits, so without this gate the lottery
+            // could push a node past its own `max`.
+            const maxRunning = isRoot && this.shared ? this.stateView[RUNNING_INDEX] : this.running;
+            if (maxRunning >= this.#max) {
+                break;
+            }
+            // Per-priority selection is measured against the GLOBAL total for the root (its caps
+            // are global reservations) but against this child's OWN direct count (#directRunning)
+            // for a child — so a child's per-priority caps are not polluted by descendant slots.
+            const capRunning = isRoot ? maxRunning : this.#directRunning;
+            const queue = this.getNextQueue(this.#limits, capRunning);
+            if (queue === null) {
+                break;
+            }
+            // Acquire a global slot. For the root this is its own counter; for a child it is the
+            // whole parent chain (#tryAcquireGlobal), which can still deny on a parent's cap.
+            if (isRoot) {
+                if (this.shared) {
+                    Atomics.add(this.stateView, RUNNING_INDEX, 1);
+                }
+                this.running += 1;
+            }
+            else {
+                if (!this.#parent.#tryAcquireGlobal()) {
+                    break;
+                }
+                this.#directRunning += 1;
+                this.running += 1;
+            }
+            const fn = queue.arr[queue.idx];
+            queue.arr[queue.idx++] = null;
+            const opaque = queue.arr[queue.idx];
+            queue.arr[queue.idx++] = null;
+            queue.cnt -= 1;
+            if (queue.cnt === 0) {
+                this.nonEmptyMask &= ~(1 << queue.i);
+                queue.idx = 0;
+                queue.arr = [];
+            }
+            else if (queue.idx > 1024) {
+                queue.arr.splice(0, queue.idx);
+                queue.idx = 0;
+            }
+            this.pending -= 1;
+            progressed = true;
+            try {
+                fn(opaque);
+            }
+            catch (err) {
+                // Balance the slot we just took (release() routes through the hierarchy path;
+                // #driving keeps the nested drive from re-entering), then isolate the failure.
+                this.release();
+                queueMicrotask(() => {
+                    throw err;
+                });
+            }
+        }
+        return progressed;
+    }
+    // Dispatch this node and, round-robin, every descendant. Returns true if any task ran in
+    // the subtree. The cursor rotation gives siblings a fair share of freed global capacity
+    // when the pool is over-subscribed (no sibling drains fully first every pass).
+    #dispatchSubtree() {
+        if (this.dead) {
+            return false;
+        }
+        let progressed = this.#drainSelf();
+        const children = this.#children;
+        if (children !== null && children.length > 0) {
+            // A dispatched fn may synchronously dispose a sibling, which splices #children
+            // mid-iteration. Bound the loop by the count captured here and null-check each slot
+            // (the index can fall past a shrunk array) so a concurrent removal can't crash the
+            // drive or read undefined. A disposed child is dead, so its #dispatchSubtree no-ops.
+            const start = this.#driveCursor;
+            const n = children.length;
+            for (let k = 0; k < n; k++) {
+                const len = children.length;
+                if (len === 0) {
+                    break;
+                }
+                const node = children[(start + k) % len];
+                if (node !== undefined && node.#dispatchSubtree()) {
+                    progressed = true;
+                }
+            }
+            const len = children.length;
+            this.#driveCursor = len > 0 ? (start + 1) % len : 0;
+        }
+        return progressed;
+    }
+    // Root-coordinated dispatch for child() hierarchies. Replaces #schedule/#maybeWait for
+    // any scheduler that is part of a tree. Re-entrancy is guarded by #driving (a synchronous
+    // release inside a dispatched fn just decrements counters; the outer loop re-reads them
+    // and picks up the freed capacity).
+    #driveLoop() {
+        if (this.dead || this.#driving) {
+            return;
+        }
+        this.#driving = true;
+        try {
+            for (;;) {
+                const expected = this.shared ? this.stateView[RUNNING_INDEX] : 0;
+                if (this.#dispatchSubtree()) {
+                    continue; // dispatched something — re-attempt (freed/created capacity may allow more)
+                }
+                // Nothing dispatched this pass.
+                if (!this.shared || this.#waitPromise !== null || this.#max === 0) {
+                    // Non-shared: local releases redrive #driveLoop directly, no futex to park on.
+                    break;
+                }
+                if (!this.#subtreeHasPending()) {
+                    break;
+                }
+                const running = this.stateView[RUNNING_INDEX];
+                if (running !== expected) {
+                    continue; // a concurrent release changed capacity — re-attempt before parking
+                }
+                if (running < this.#max) {
+                    // GLOBAL headroom exists yet we dispatched nothing. Two cases:
+                    if (this.running > 0) {
+                        // This worker holds running tasks → it is blocked on a LOCAL child cap, which
+                        // only a local release can free (and that redrives #driveLoop directly). The
+                        // headroom is shared, though: a peer whose child is below its cap could use it,
+                        // and notify(1) on the releasing side may have woken THIS worker (which can't
+                        // use the slot). Forward the wakeup so the slot is not stranded while a peer's
+                        // backlog hangs; the chain stops when capacity is consumed or no waiter remains.
+                        if (this.stateView[WAITERS_INDEX] > 0) {
+                            Atomics.notify(this.stateView, RUNNING_INDEX, 1);
+                        }
+                        break;
+                    }
+                    // We hold NOTHING yet headroom exists: a peer won the acquire race during this
+                    // pass (RUNNING transiently hit max while we read it in #tryAcquireGlobal). There
+                    // is no local task to ever redrive us, so we must NOT break — retry; the next
+                    // #tryAcquireGlobal grabs the slot once the transient spike clears. (Parking here
+                    // would strand us with idle capacity, since the freeing release already fired.)
+                    continue;
+                }
+                // Globally saturated with pending work: park on RUNNING. Bump WAITERS, then re-read
+                // RUNNING (a release in the window skipped notify while WAITERS was 0); waitAsync's
+                // atomic compare against `expected` covers the remaining window up to the park.
+                Atomics.add(this.stateView, WAITERS_INDEX, 1);
+                if (this.stateView[RUNNING_INDEX] !== expected) {
+                    Atomics.sub(this.stateView, WAITERS_INDEX, 1);
+                    continue;
+                }
+                const { value, async } = Atomics.waitAsync(this.stateView, RUNNING_INDEX, expected);
+                this.#waitPromise = (async ? value : Promise.resolve(value)).then(() => {
+                    if (this.dead) {
+                        Atomics.notify(this.stateView, RUNNING_INDEX, 1);
+                        return;
+                    }
+                    Atomics.sub(this.stateView, WAITERS_INDEX, 1);
+                    this.#waitPromise = null;
+                    this.#driveLoop();
+                });
+                break;
+            }
+        }
+        finally {
+            this.#driving = false;
+        }
+    }
+    // Release path for any scheduler in a child() hierarchy: free one slot up the chain, then
+    // re-drive the whole tree from the root.
+    #releaseHierarchy() {
+        if (this.running > 0) {
+            this.running -= 1;
+            if (this.#parent !== null) {
+                // This release is for one of THIS node's own direct tasks (release() is always
+                // called on the node the task ran through), so pair the #directRunning increment.
+                if (this.#directRunning > 0) {
+                    this.#directRunning -= 1;
+                }
+                this.#parent.#releaseGlobal();
+            }
+            else if (this.shared) {
+                Atomics.sub(this.stateView, RUNNING_INDEX, 1);
+                if (this.stateView[WAITERS_INDEX] > 0) {
+                    Atomics.notify(this.stateView, RUNNING_INDEX, 1);
+                }
+            }
+        }
+        this.#root().#driveLoop();
+    }
     release = () => {
         // After [kOnExit], all bookkeeping for this scheduler has been finalised
         // and any leftover microtasks must NOT touch shared state. See the dead
@@ -447,6 +940,10 @@ export class Scheduler extends Queue {
         if (this.dead) {
             return;
         }
+        if (this.#parent !== null || this.#children !== null) {
+            this.#releaseHierarchy();
+            return;
+        }
         let running;
         if (this.running > 0) {
             this.running -= 1;
@@ -473,15 +970,47 @@ export class Scheduler extends Queue {
         else {
             running = this.shared ? this.stateView[RUNNING_INDEX] : this.running;
         }
-        this.#schedule(running);
+        // Skip the (non-inlined) #schedule call entirely when nothing is queued —
+        // measurably cheaper on the no-backlog acquire/release hot path, and
+        // semantically identical (#schedule with pending === 0 is a no-op).
+        if (this.pending !== 0) {
+            this.#schedule(running);
+        }
     };
     [Symbol.dispose]() {
         if (this.dead) {
             return;
         }
-        // Reuse the exit-cleanup path: release any global slots this instance still holds,
-        // pair the WAITERS increment of a parked waitAsync, and mark the instance dead so any
-        // late notify .then microtask becomes a no-op (see the `dead` field docstring).
+        // Dispose descendants first: reject their queued run() promises and release the global
+        // slots they hold back up to us (so our own kOnExit below accounts only for OUR direct
+        // slots, not theirs — avoiding a double release of the same SAB slot).
+        const children = this.#children;
+        if (children !== null) {
+            this.#children = null;
+            for (const c of children.slice()) {
+                c[Symbol.dispose]();
+            }
+        }
+        // If we are a child, hand the slots we still hold back up the chain and unregister from
+        // the parent so the freed capacity can be reused and we can be GC'd.
+        const parent = this.#parent;
+        if (parent !== null) {
+            const held = this.running;
+            this.running = 0;
+            this.#directRunning = 0;
+            for (let i = 0; i < held; i++) {
+                parent.#releaseGlobal();
+            }
+            if (parent.#children !== null) {
+                const idx = parent.#children.indexOf(this);
+                if (idx >= 0) {
+                    parent.#children.splice(idx, 1);
+                }
+            }
+        }
+        // Reuse the exit-cleanup path: release any global slots THIS instance still holds (root
+        // shared mode), pair the WAITERS increment of a parked waitAsync, and mark the instance
+        // dead so any late notify .then microtask becomes a no-op (see the `dead` docstring).
         this[kOnExit]();
         // Reject queued run() promises so callers awaiting them fail fast instead of
         // hanging forever — the dead-guard in run() only covers calls made AFTER dispose,
@@ -498,12 +1027,23 @@ export class Scheduler extends Queue {
             queue.idx = 0;
             queue.cnt = 0;
         }
+        this.nonEmptyMask = 0;
         // Drop our reference to the parked waitAsync chain and remove the strong ref that the
         // exit registry holds, so the instance — and the .then closure capturing it — can be
         // garbage-collected without waiting for process exit. Cleanup already ran above, so
         // there is nothing left for process.on('exit') to do for this instance.
         this.#waitPromise = null;
         schedulers.delete(this);
+        // A freed child slot may let the parent or our siblings dispatch now — BUT only when
+        // this is an isolated child dispose, not when the parent is disposing the whole tree.
+        // A parent's dispose nulls its #children before disposing each descendant; re-driving it
+        // then would dispatch the parent's OWN still-queued direct tasks mid-disposal (running
+        // user callbacks that the parent is about to reject), violating dispose's contract. A
+        // node that has a child always has a non-null #children EXCEPT during its own dispose,
+        // so `parent.#children !== null` is exactly "parent still an active hierarchy node".
+        if (parent !== null && parent.#children !== null) {
+            parent.#root().#driveLoop();
+        }
     }
 }
 //# sourceMappingURL=scheduler.js.map