A {@code SingleConsumerQueue} is an appropriate choice when many producer threads will share + * access to a common collection and a single consumer thread drains it. This collection is useful + * in scenarios such as implementing flat combining, actors, or lock amortization. + * + *
This implementation employs combination to transfer elements between threads that are + * producing concurrently. This approach avoids contention on the queue by combining colliding + * operations that have identical semantics. When a pair of producers collide, the task of + * performing the combined set of operations is delegated to one of the threads and the other thread + * optionally waits for its operation to be completed. This decision of whether to wait for + * completion is determined by constructing either a linearizable or optimistic + * queue. + * + *
Iterators are weakly consistent, returning elements reflecting the state of the queue + * at some point at or since the creation of the iterator. They do not throw {@link + * java.util.ConcurrentModificationException}, and may proceed concurrently with other operations. + * Elements contained in the queue since the creation of the iterator will be returned exactly once. + * + *
Beware that it is the responsibility of the caller to ensure that a consumer has exclusive + * read access to the queue. This implementation does not include fail-fast behavior to + * guard against incorrect consumer usage. + * + *
Beware that, unlike in most collections, the {@code size} method is NOT a + * constant-time operation. Because of the asynchronous nature of these queues, determining the + * current number of elements requires a traversal of the elements, and so may report inaccurate + * results if this collection is modified during traversal. + * + *
Warning: This class is scheduled for removal in version 3.0.0.
+ *
+ * @author ben.manes@gmail.com (Ben Manes)
+ * @param