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 and OOM-like symptoms (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

Add @deprecated(since = "2.0.0") annotations to the four Source.queue overloads that accept an OverflowStrategy:

• scaladsl.Source.queue[T](bufferSize, overflowStrategy)
• scaladsl.Source.queue[T](bufferSize, overflowStrategy, maxConcurrentOffers)
• javadsl.Source.queue[T](bufferSize, overflowStrategy)
• javadsl.Source.queue[T](bufferSize, overflowStrategy, maxConcurrentOffers)

The Source.queue[T](bufferSize) overloads that return a BoundedSourceQueue are not deprecated and remain the recommended path.

The SourceQueue / SourceQueueWithComplete traits are not deprecated (they are still referenced by the deprecated factory return types and by user code); only the factory entry points are marked deprecated so users see the signal at the call site without cascading warnings.

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). This closes the documented hang trap at the API level without breaking binary compatibility.

Tests

Not run - API surface change only (annotation addition, no behavior change). The deprecation annotations are verified by the compiler on every compilation of user code.

A follow-up may add a @nowarn guard or a compile-time test to ensure the warning surfaces, but that is out of scope for this PR.

References

• Refs Replace old Source.queue akka/akka-core#29801 (Replace old Source.queue - OPEN, stale since 2021)
• Refs Async callback tracking in GraphStage can lead to OOM if callbacks cannot be processed fast enough akka/akka-core#29557 (Async callback tracking OOM in Source.queue)
• Refs akka/akka.net#8248 (Akka.NET's cancellation-aware Source.Queue offer, motivating the same review)