He-Pin opened a new pull request, #3095:
URL: https://github.com/apache/pekko/pull/3095
### Motivation
The `Source.queue(bufferSize, overflowStrategy)` overloads (both Scala and
Java DSLs) materialize a `SourceQueueWithComplete` whose asynchronous `offer`
future can hang indefinitely under `OverflowStrategy.backpressure` when the
buffer is full and downstream stalls. This is a long-standing trap that has
caused real-world deadlocks (the same class of issue was documented upstream as
akka/akka-core#29557, and more recently prompted akka/akka.net#8248 to add a
cancellation-aware offer overload).
Pekko already provides a safer replacement:
- `Source.queue[T](bufferSize)` materializes a `BoundedSourceQueue` with
synchronous feedback (drops the newest element when the buffer is full, never
hangs).
- For backpressure scenarios, `Source.actorRefWithBackpressure` and
`MergeHub.source` cover the common use cases.
The upstream Akka discussion in akka/akka-core#29801 ("Replace old
Source.queue") has been open since 2021 without converging on a new
backpressure primitive. We should not wait: the drop-new path
(`BoundedSourceQueue`) is already stable and production-proven, and the
backpressure path is covered by existing operators.
### Modification
1. **API deprecation**: `@deprecated(since = "2.0.0")` on the four
`Source.queue` overloads that accept an `OverflowStrategy` (two scaladsl + two
javadsl). `Source.queue[T](bufferSize)` overloads that return
`BoundedSourceQueue` are **not** deprecated. `SourceQueue` /
`SourceQueueWithComplete` traits are not deprecated (they are still referenced
by the deprecated factory return types and by user code).
2. **Internal suppression**: `@nowarn("msg=deprecated")` on the deprecated
factories (so their delegation chain does not retrigger the warning under
`-Xfatal-warnings` / `-Werror`) and on the two Pekko-internal call sites that
intentionally exercise the deprecated API: `InvokeWithFeedbackBenchmark` and
`QueueSourceSpec`.
3. **Docs**: rewrite `docs/.../Source/queue.md` to lead with the
non-deprecated `BoundedSourceQueue` path, add a `@@@ warning` callout flagging
the deprecated overloads, and add a migration table mapping each
`OverflowStrategy` to its replacement. Update the Scala `#source-queue` snippet
in `IntegrationDocSpec.scala` to match the Java counterpart (both now use
`BoundedSourceQueue` with a direct `match`/`switch` on `QueueOfferResult`).
Drop "or SourceQueue" from the one-line summary in `operators/index.md`.
### Result
- Users calling `Source.queue(...)` with an `OverflowStrategy` get a
compile-time deprecation warning pointing them to `Source.queue(bufferSize)`
for drop-new, or `Source.actorRefWithBackpressure` / `MergeHub.source` for
backpressure.
- The hang trap is closed at the API level without breaking binary
compatibility (the deprecated methods are unchanged, only annotated).
- Pekko internal code is free of deprecation warnings under
`-Xfatal-warnings`.
- Docs page now steers readers toward the recommended path and documents an
explicit migration for every overflow strategy.
### Tests
- `sbt "stream / compile"` — pass (213 Scala + 5 Java sources)
- `sbt "stream-tests / Test / compile"` — pass (229 Scala + 32 Java sources)
- `sbt "bench-jmh / compile"` — pass (98 Scala + 1 Java sources)
- `sbt "docs / Test / compile"` — pass (224 Scala + 234 Java sources;
updated `#source-queue` snippet type-checks against `BoundedSourceQueue.offer`
returning `QueueOfferResult`)
### References
- Fixes apache/pekko#3094
- Refs akka/akka-core#29801 (Replace old Source.queue — OPEN, stale since
2021)
- Refs akka/akka-core#29557 (Async callback tracking OOM in Source.queue)
- Refs akka/akka.net#8248 (Akka.NET cancellation-aware Source.Queue offer,
motivating the same review)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
