optimize: avoid Holder allocation in ordered mapAsync for already-completed futures

[He-Pin]

Motivation

Ordered MapAsync allocates a Holder and performs a buffer enqueue/dequeue round-trip for every element, even when the future returned by the user function is already completed successfully and could be emitted immediately. With a synchronously-completing function (caching, Future.successful, conditional async, ...) this is pure per-element garbage.

Note: mapAsync(1) delegates to mapAsyncUnordered(1) (Flow.scala), and MapAsyncUnordered already pushes completed results straight through without a Holder. The allocation only existed in the ordered stage at parallelism >= 2.

Modification

In MapAsync.onPush, add a zero-allocation fast path: when the future is already completed with a non-null element, nothing is buffered ahead of it (so ordering is already satisfied) and downstream demand is present, push the element straight through without allocating a Holder or touching the buffer.

The not-yet-completed (None) case is matched first, so the pending path is unchanged: a single type check that never evaluates the fast-path guard (behaviourally and cost-wise identical to before).

Result

JMH MapAsyncBenchmark (parallelism=4, spawn=false): 18.0M -> 20.3M ops/s (+12%), with the per-element Holder allocation eliminated (confirmed via async-profiler alloc profile: Holder disappears; remaining allocation is the user's Success box from Future.successful). No regression on the asynchronous path (spawn=true, within run-to-run noise).

Tests

• sbt "stream-tests/testOnly *FlowMapAsyncSpec" — 27/27 green. Existing coverage already exercises the fast path: "produce future elements in order" mixes Future.successful with async futures, and mapAsync(2)(Future.successful(_)) drives ordered + already-completed.
• sbt stream/Compile/compile, stream/scalafmt, stream/headerCheck, stream/mimaReportBinaryIssues — all green (binary compatible, internal API only).

References

• bench-jmh MapAsyncBenchmark
• Relates to the existing already-completed-future optimization (#20217).

[Copilot]

Pull request overview

This PR optimizes the ordered MapAsync GraphStage to avoid per-element Holder allocation and buffer round-trips when the user function returns an already-successfully-completed Future and ordering is trivially satisfied (no buffered elements ahead, downstream demand present).

Changes:

• Adds a fast path in MapAsync.onPush to immediately push already-completed successful (non-null) results when buffer.isEmpty and isAvailable(out).
• Keeps the pending (None) path behavior/cost essentially unchanged by matching it first, and retains existing failure/supervision handling for other completed cases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pjfanning]

lgtm