You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@pekko.apache.org by "He-Pin (via GitHub)" <gi...@apache.org> on 2026/10/10 06:40:59 UTC

[I] stream: synchronous source queue with overflow strategies (ConcurrentLinkedQueue-backed dropHead) [pekko]

He-Pin opened a new issue, #3612:
URL: https://github.com/apache/pekko/issues/3612

   ### Background
   
   The `Source.queue(n, OverflowStrategy)` overloads that materialize a `SourceQueueWithComplete` are deprecated (#3094), and the migration docs (#3458, #3605) point users to:
   
   - `Source.queue[T](n)` (a `BoundedSourceQueue`) — but it only has drop-new semantics
   - `Source.actorRef(completionMatcher, failureMatcher, n, OverflowStrategy.dropHead/dropTail/dropBuffer)` — exact eviction semantics, but the producer has to switch from a synchronous `offer` with `QueueOfferResult` feedback to fire-and-forget `tell`
   - or a custom `GraphStage`
   
   A synchronous, strategy-aware queue source would close this gap without pushing producers onto the actor API.
   
   ### Why the current implementation cannot just grow strategies
   
   `BoundedSourceQueueStage` is backed by `AbstractBoundedNodeQueue`, which is a **MPSC** (multi-producer, single-consumer) Vyukov queue — the stage logic is the only allowed consumer (`run()` polls it). `dropHead` requires the **producer** to evict the oldest element on offer, i.e. act as a second consumer, which violates the MPSC contract.
   
   ### Proposal
   
   Switch the backing queue implementation per strategy:
   
   | Strategy | Backing queue | offer behavior |
   |---|---|---|
   | drop-new (default) | keep `AbstractBoundedNodeQueue` (MPSC, preallocated, unchanged fast path) | `add` fails when full -> `Dropped` |
   | dropHead | `ConcurrentLinkedQueue` (MPMC-safe) + size counter | always `add`; if `size.incrementAndGet() > n`, evict via `poll()` -> always `Enqueued` |
   | fail (optional) | either | full -> fail the stage and return `Failure` synchronously |
   
   Sketch of the dropHead offer path, reusing the existing `NeedsActivation` wakeup protocol from `BoundedSourceQueueStage`:
   
   ```scala
   final override def offer(elem: T): QueueOfferResult = state.get() match {
     case Running | NeedsActivation =>
       queue.add(elem) // ConcurrentLinkedQueue never rejects
       if (size.incrementAndGet() > bufferSize && queue.poll() != null)
         size.decrementAndGet() // evict the oldest element
       if (state.get() == NeedsActivation && clearNeedsActivation())
         logic.callback.invoke(())
       QueueOfferResult.Enqueued
     case Done(result) => result
   }
   ```
   
   ### Semantics and trade-offs
   
   - **Single producer: exact** — keeps the latest `n` elements, offer never rejects, matching the deprecated overloads.
   - **Multiple producers: approximate** — the deprecated actor-based queue serialized offers through the mailbox (exact), while concurrent offers on a CLQ can transiently exceed `n` (bounded by the number of concurrent producers) and eviction order can be slightly imprecise. This seems acceptable for typical dropHead uses (latest-value feeds, sampling) but must be documented.
   - `size()` becomes approximate under concurrency.
   - `ConcurrentLinkedQueue` allocates a node per element, which is why the default drop-new path should keep the zero-allocation MPSC queue and only the strategy variants switch implementation.
   
   ### API considerations
   
   - `Source.queue(Int, OverflowStrategy)` cannot be overloaded with a different materialized type — erasure clash with the deprecated overloads. One option is a dedicated strategy enum (e.g. `QueueEvictionStrategy { DropNew, DropHead, Fail }`) as the overload parameter, materializing the existing public `BoundedSourceQueue[T]` trait.
   - `dropTail` is out of scope for a first version: removing the youngest buffered element is O(n) on a linked queue, and `ConcurrentLinkedDeque.removeLast` races with concurrent adds. dropTail users keep the `Source.actorRef` migration path.
   - `dropBuffer` (clear on overflow) is possible on a CLQ with approximate semantics — a candidate for a later iteration.
   - Would need Scala and Java DSL parity, `@ApiMayChange`, additive-only MiMa impact, and concurrency stress tests in addition to the directional eviction tests.
   
   ### References
   
   - #3094, #3458 — deprecation and migration guide for the old overloads
   - #3605 — migration examples; its review discussion surfaced this gap
   - `stream/src/main/scala/org/apache/pekko/stream/impl/BoundedSourceQueue.scala` — stage and wakeup protocol to reuse
   - `actor/src/main/java/org/apache/pekko/dispatch/AbstractBoundedNodeQueue.java` — MPSC contract
   - `stream/src/main/scala/org/apache/pekko/stream/impl/ActorRefSource.scala` — current exact dropHead/dropTail/dropBuffer path
   


-- 
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: notifications-unsubscribe@pekko.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@pekko.apache.org
For additional commands, e-mail: notifications-help@pekko.apache.org