From 4a8b7409af3e162aaf4620fee5e7bc815030485f Mon Sep 17 00:00:00 2001
From: Simone Bordet <simone.bordet@gmail.com>
Date: Wed, 13 Mar 2013 22:57:37 +0100
Subject: [PATCH] Second draft implementation of bounded and unbounded
 ConcurrentArrayBlockingQueue.

---
 .../util/ConcurrentArrayBlockingQueue.java      | 17 +++++++++++++++++
 .../jetty/util/ConcurrentArrayQueue.java        | 14 ++++++++++++++
 ...currentArrayBlockingQueueUnboundedTest.java} |  9 +++++++--
 3 files changed, 38 insertions(+), 2 deletions(-)
 rename jetty-util/src/test/java/org/eclipse/jetty/util/{ConcurrentArrayBlockingQueueTest.java => ConcurrentArrayBlockingQueueUnboundedTest.java} (93%)

diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueue.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueue.java
index b7409b3c46e..a847be36937 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueue.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueue.java
@@ -27,6 +27,13 @@ import java.util.concurrent.locks.Condition;
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReentrantLock;
 
+/**
+ * Common functionality for a blocking version of {@link ConcurrentArrayQueue}.
+ *
+ * @see Unbounded
+ * @see Bounded
+ * @param <T>
+ */
 public abstract class ConcurrentArrayBlockingQueue<T> extends ConcurrentArrayQueue<T> implements BlockingQueue<T>
 {
     private final Lock _lock = new ReentrantLock();
@@ -163,6 +170,11 @@ public abstract class ConcurrentArrayBlockingQueue<T> extends ConcurrentArrayQue
         signalProducers();
     }
 
+    /**
+     * An unbounded, blocking version of {@link ConcurrentArrayQueue}.
+     *
+     * @param <E>
+     */
     public static class Unbounded<E> extends ConcurrentArrayBlockingQueue<E>
     {
         private static final int HEAD_OFFSET = MemoryUtils.getLongsPerCacheLine() - 1;
@@ -245,6 +257,11 @@ public abstract class ConcurrentArrayBlockingQueue<T> extends ConcurrentArrayQue
         }
     }
 
+    /**
+     * A bounded, blocking version of {@link ConcurrentArrayQueue}.
+     *
+     * @param <E>
+     */
     public static class Bounded<E> extends ConcurrentArrayBlockingQueue<E>
     {
         private final AtomicInteger _size = new AtomicInteger();
diff --git a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
index 3c64234cc41..493197f8bc2 100644
--- a/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
+++ b/jetty-util/src/main/java/org/eclipse/jetty/util/ConcurrentArrayQueue.java
@@ -25,9 +25,23 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.NoSuchElementException;
 import java.util.Objects;
+import java.util.Queue;
+import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.concurrent.atomic.AtomicReferenceArray;
 
+/**
+ * A concurrent, unbounded implementation of {@link Queue} that uses singly-linked array blocks
+ * to store elements.
+ * <p/>
+ * This class is a drop-in replacement for {@link ConcurrentLinkedQueue}, with similar performance
+ * but producing less garbage because arrays are used to store elements rather than nodes.
+ * <p/>
+ * The algorithm used is a variation of the algorithm from Gidenstam, Sundell and Tsigas
+ * (http://www.adm.hb.se/~AGD/Presentations/CacheAwareQueue_OPODIS.pdf).
+ *
+ * @param <T>
+ */
 public class ConcurrentArrayQueue<T> extends AbstractQueue<T>
 {
     public static final int DEFAULT_BLOCK_SIZE = 512;
diff --git a/jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueTest.java b/jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueUnboundedTest.java
similarity index 93%
rename from jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueTest.java
rename to jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueUnboundedTest.java
index 0ff4c6137e1..10127ec9480 100644
--- a/jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueTest.java
+++ b/jetty-util/src/test/java/org/eclipse/jetty/util/ConcurrentArrayBlockingQueueUnboundedTest.java
@@ -27,15 +27,20 @@ import java.util.concurrent.Executors;
 import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
 
+import org.eclipse.jetty.toolchain.test.TestTracker;
 import org.junit.Assert;
+import org.junit.Rule;
 import org.junit.Test;
 
-public class ConcurrentArrayBlockingQueueTest extends ConcurrentArrayQueueTest
+public class ConcurrentArrayBlockingQueueUnboundedTest extends ConcurrentArrayQueueTest
 {
+    @Rule
+    public final TestTracker tracker = new TestTracker();
+
     @Override
     protected ConcurrentArrayBlockingQueue<Integer> newConcurrentArrayQueue(int blockSize)
     {
-        return new ConcurrentArrayBlockingQueue<>(blockSize);
+        return new ConcurrentArrayBlockingQueue.Unbounded<>(blockSize);
     }
 
     @Test