diff --git a/src/main/java/org/ice4j/util/PacketQueue.java b/src/main/java/org/ice4j/util/PacketQueue.java
new file mode 100644
index 0000000..6ccf8ea
--- /dev/null
+++ b/src/main/java/org/ice4j/util/PacketQueue.java
@@ -0,0 +1,524 @@
+/*
+ * Copyright @ 2015 Atlassian Pty Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.ice4j.util;
+
+import java.util.*;
+import java.util.concurrent.*;
+import java.util.logging.*;
+
+/**
+ * An abstract queue of packets. This is meant to eventually be able to be used
+ * in the following classes (in ice4j and libjitsi) in place of their ad-hoc
+ * queue implementations (which is the reason the class is parametrized):
+ *
RTPConnectorOutputStream.Queue
+ *
PushSourceStreamImpl#readQ
+ *
OutputDataStreamImpl#writeQ
+ *
SinglePortHarvester.MySocket#queue
+ *
MultiplexingSocket#received (and the rest of Multiplex* classes).
+ *
+ * @author Boris Grozev
+ */
+public abstract class PacketQueue
+{
+ /**
+ * The {@link Logger} used by the {@link PacketQueue} class and its
+ * instances for logging output.
+ */
+ private static final Logger logger
+ = Logger.getLogger(PacketQueue.class.getName());
+
+ /**
+ * The default capacity of a {@link PacketQueue}.
+ */
+ private final static int DEFAULT_CAPACITY = 256;
+
+ /**
+ * The capacity of the {@code byte[]} cache, if it is enabled.
+ */
+ private final static int CACHE_CAPACITY = 100;
+
+ /**
+ * Returns true if a warning should be logged after a queue has dropped
+ * {@code numDroppedPackets} packets.
+ * @param numDroppedPackets the number of dropped packets.
+ * @return {@code true} if a warning should be logged.
+ */
+ public static boolean logDroppedPacket(int numDroppedPackets)
+ {
+ return
+ numDroppedPackets == 1 ||
+ (numDroppedPackets <= 1000 && numDroppedPackets % 100 == 0) ||
+ numDroppedPackets % 1000 == 0;
+ }
+
+ /**
+ * The underlying {@link Queue} which holds packets.
+ */
+ private final Queue queue;
+
+ /**
+ * Whether this {@link PacketQueue} should store the {@code byte[]} or
+ * {@code T} instances added to it via on of the {@code add} methods (of
+ * {@code false}), or create and store a copy (if {@code true}).
+ */
+ private final boolean copy;
+
+ /**
+ * A cache optionally used to reduce the allocation of new {@code byte[]}
+ * instances.
+ */
+ private final Queue cache;
+
+ /**
+ * The capacity of this {@link PacketQueue}. If one of the {@code add}
+ * methods is called while the queue holds this many packets, the first
+ * packet in the queue will be dropped.
+ */
+ private final int capacity;
+
+ /**
+ * The {@link QueueStatistics} instance optionally used to collect and print
+ * detailed statistics about this queue.
+ */
+ private final QueueStatistics queueStatistics;
+
+ /**
+ * The {@link Thread} optionally used to perpetually read packets from this
+ * queue and handle them using {@link #handler}.
+ */
+ private final Thread thread;
+
+ /**
+ * The {@link org.ice4j.util.PacketQueue.PacketHandler} optionally used to
+ * handle packets read from this queue by {@link #thread}.
+ */
+ private final PacketHandler handler;
+
+ /**
+ * A string used to identify this {@link PacketQueue} for logging purposes.
+ */
+ private final String id;
+
+ /**
+ * Whether this queue has been closed.
+ */
+ private boolean closed = false;
+
+ /**
+ * The number of packets which were dropped from this {@link PacketQueue} as
+ * a result of a packet being added while the queue is at full capacity.
+ */
+ private int numDroppedPackets = 0;
+
+ /**
+ * Initializes a new {@link PacketQueue} instance.
+ */
+ public PacketQueue()
+ {
+ this(false, "PacketQueue", null);
+ }
+
+ /**
+ * Initializes a new {@link PacketQueue} instance.
+ * @param enableStatistics whether detailed statistics should be calculated
+ * and printed. WARNING: this will produce copious output (one line per
+ * packet added or removed).
+ * @param id the ID of the packet queue, to be used for logging.
+ * @param packetHandler An optional handler to be used by the queue for
+ * packets read from it. If a non-null value is passed the queue will
+ * start its own thread, which will read packets from the queue and execute
+ * {@code handler.handlePacket} on them. If set to null, no thread will be
+ * created, and the queue will provide access to the head element via
+ * {@link #get()} and {@link #poll()}.
+ */
+ public PacketQueue(
+ boolean enableStatistics, String id, PacketHandler packetHandler)
+ {
+ this(DEFAULT_CAPACITY, true, true, enableStatistics, id, packetHandler);
+ }
+
+ /**
+ * Initializes a new {@link PacketQueue} instance.
+ * @param capacity the capacity of the queue.
+ * @param enableCache whether caching of unused {@code byte[]} instances
+ * should be enabled.
+ * @param copy whether the queue is to store the instances it is given via
+ * the various {@code add} methods, or create a copy.
+ * @param enableStatistics whether detailed statistics should be calculated
+ * and printed. WARNING: this will produce copious output (one line per
+ * packet added or removed).
+ * @param id the ID of the packet queue, to be used for logging.
+ * @param packetHandler An optional handler to be used by the queue for
+ * packets read from it. If a non-null value is passed the queue will
+ * start its own thread, which will read packets from the queue and execute
+ * {@code handler.handlePacket} on them. If set to null, no thread will be
+ * created, and the queue will provide access to the head element via
+ * {@link #get()} and {@link #poll()}.
+ */
+ public PacketQueue(int capacity, boolean enableCache, boolean copy,
+ boolean enableStatistics, String id,
+ PacketHandler packetHandler)
+ {
+ this.copy = copy;
+ this.capacity = capacity;
+ this.id = id;
+ queue = new ArrayBlockingQueue<>(capacity);
+
+ queueStatistics
+ = enableStatistics ? new QueueStatistics(id) : null;
+
+ cache
+ = enableCache
+ ? new ArrayBlockingQueue(CACHE_CAPACITY) : null;
+
+ if (packetHandler != null)
+ {
+ handler = packetHandler;
+
+ thread = new Thread(){
+ @Override
+ public void run()
+ {
+ runInReadingThread();
+ }
+ };
+ thread.setName(getClass().getName() + "-" + id);
+ thread.setDaemon(true);
+ thread.start();
+ }
+ else
+ {
+ thread = null;
+ handler = null;
+ }
+
+ logger.info("Initialized a PacketQueue instance with ID " + id);
+ }
+
+ /**
+ * Perpetually reads packets from this {@link PacketQueue} and uses
+ * {@link #handler} on each of them.
+ */
+ private void runInReadingThread()
+ {
+ if (Thread.currentThread() != thread)
+ {
+ logger.warning("runInReadingThread executing in "
+ + Thread.currentThread());
+ return;
+ }
+
+ if (handler == null)
+ {
+ logger.warning("No handler set, the reading thread will be stopped.");
+ return;
+ }
+
+ while (!closed)
+ {
+ T pkt;
+
+ synchronized (queue)
+ {
+ pkt = queue.poll();
+ if (pkt == null)
+ {
+ try
+ {
+ queue.wait(100);
+ }
+ catch (InterruptedException ie)
+ {
+ }
+ continue;
+ }
+ }
+
+ if (queueStatistics != null)
+ {
+ queueStatistics.remove(System.currentTimeMillis());
+ }
+
+ try
+ {
+ handler.handlePacket(pkt);
+ }
+ catch (Exception e)
+ {
+ logger.warning("Failed to handle packet: " + e);
+ }
+ }
+ }
+
+ /**
+ * Adds a packet represented by a {@code byte[]} with a corresponding
+ * offset and length to this queue.
+ * @param buf the {@code byte[]} to add.
+ * @param off the offset into {@code byte[]} where data begins.
+ * @param len the length of the data.
+ */
+ public void add(byte[] buf, int off, int len)
+ {
+ add(buf, off, len, null);
+ }
+
+ /**
+ * Adds a packet represented by a {@code byte[]} with a corresponding
+ * offset and length, and a context object to this queue.
+ * @param buf the {@code byte[]} to add.
+ * @param off the offset into {@code byte[]} where data begins.
+ * @param len the length of the data.
+ * @param context an object which will be added to the queue as part of the
+ * packet.
+ */
+ public void add(byte[] buf, int off, int len, Object context)
+ {
+ if (copy)
+ {
+ byte[] newBuf = getByteArray(len);
+ System.arraycopy(buf, off, newBuf, 0, len);
+ doAdd(createPacket(newBuf, 0, len, context));
+ }
+ else
+ {
+ doAdd(createPacket(buf, off, len, context));
+ }
+ }
+
+ /**
+ * Adds a specific packet ({@code T}) instance to the queue.
+ * @param pkt the packet to add.
+ */
+ public void add(T pkt)
+ {
+ if (copy)
+ {
+ // create a new instance
+ add(getBuffer(pkt), getOffset(pkt), getLength(pkt), getContext(pkt));
+ }
+ else
+ {
+ doAdd(pkt);
+ }
+ }
+
+ /**
+ * Get an unused {@link byte[]} instance with length at least {@code len}.
+ * @param len the minimum length of the returned instance.
+ * @return a {@link byte[]} instance with length at least {@code len}.
+ */
+ private byte[] getByteArray(int len)
+ {
+ if (cache != null)
+ {
+ byte[] buf = cache.poll();
+ if (buf != null && buf.length >= len)
+ {
+ return buf;
+ }
+ }
+ return new byte[len];
+ }
+
+ /**
+ * Adds a specific packet ({@code T}) instance to the queue.
+ * @param pkt the packet to add.
+ */
+ private void doAdd(T pkt)
+ {
+ if (closed)
+ return;
+
+ synchronized (queue)
+ {
+ if (queue.size() >= capacity)
+ {
+ // Drop from the head of the queue.
+ T p = queue.poll();
+ if (p != null)
+ {
+ if (queueStatistics != null)
+ {
+ queueStatistics.remove(System.currentTimeMillis());
+ }
+ if (logDroppedPacket(++numDroppedPackets))
+ {
+ logger.warning(
+ "Packets dropped (id=" + id + "): " + numDroppedPackets);
+
+ }
+
+ if (cache != null && copy)
+ {
+ cache.offer(getBuffer(p));
+ }
+ }
+ }
+
+ if (queueStatistics != null)
+ {
+ queueStatistics.add(System.currentTimeMillis());
+ }
+ queue.offer(pkt);
+
+ queue.notifyAll();
+ }
+ }
+
+ /**
+ * Removes and returns the packet ({@code T}) at the head of this queue.
+ * Blocks until there is a packet in the queue. Returns {@code null} if
+ * the queue is closed or gets closed while waiting for a packet to be added.
+ * @return the packet at the head of this queue.
+ */
+ public T get()
+ {
+ if (handler != null)
+ {
+ // If the queue was configured with a handler, it is running its
+ // own reading thread, and reading from it via this interface would
+ // not provide consistent results.
+ throw new IllegalStateException(
+ "Trying to read from a queue with a configured handler.");
+ }
+
+ while (true)
+ {
+ if (closed)
+ return null;
+ synchronized (queue)
+ {
+ T pkt = queue.poll();
+ if (pkt != null)
+ {
+ if (queueStatistics != null)
+ {
+ queueStatistics.remove(System.currentTimeMillis());
+ }
+ return pkt;
+ }
+
+ try
+ {
+ queue.wait();
+ }
+ catch (InterruptedException ie)
+ {}
+ }
+ }
+ }
+
+ /**
+ * Removes and returns the packet ({@code T}) at the head of this queue, if
+ * the queue is non-empty. If the queue is closed or empty, returns null
+ * without blocking.
+ * @return the packet at the head of this queue, or null if the queue is
+ * empty.
+ */
+ public T poll()
+ {
+ if (closed)
+ return null;
+
+ if (handler != null)
+ {
+ // If the queue was configured with a handler, it is running its
+ // own reading thread, and reading from it via this interface would
+ // not provide consistent results.
+ throw new IllegalStateException(
+ "Trying to read from a queue with a configured handler.");
+ }
+
+ synchronized (queue)
+ {
+ T pkt = queue.poll();
+ if (pkt != null && queueStatistics != null)
+ {
+ queueStatistics.remove(System.currentTimeMillis());
+ }
+
+ return pkt;
+ }
+ }
+
+ public void close()
+ {
+ if (!closed)
+ {
+ closed = true;
+
+ synchronized (queue)
+ {
+ queue.notifyAll();
+ }
+ }
+ }
+
+ /**
+ * Extracts the underlying {@code byte[]} from a packet.
+ * @param pkt the packet to get the {@code byte[]} from.
+ * @return the underlying {@code byte[]} of {@code pkt}.
+ */
+ public abstract byte[] getBuffer(T pkt);
+
+ /**
+ * Extracts the offset of a packet.
+ * @param pkt the packet to get the offset of.
+ * @return the offset of {@code pkt}.
+ */
+ public abstract int getOffset(T pkt);
+
+ /**
+ * Extracts the length of a packet.
+ * @param pkt the packet to get the length of.
+ * @return the length of {@code pkt}.
+ */
+ public abstract int getLength(T pkt);
+
+ /**
+ * Extracts the context of a packet.
+ * @param pkt the packet to get the context of.
+ * @return the context of {@code pkt}.
+ */
+ public abstract Object getContext(T pkt);
+
+ /**
+ * Creates a new packet ({@link T} instance) with the given {@code byte[]},
+ * offset, length and context.
+ * @param buf the {@code byte[]} of the new instance.
+ * @param off the offset of the new instance.
+ * @param len the length of the new instance.
+ * @param context the context of the new instance.
+ * @return a new packet ({@link T} instance).
+ */
+ protected abstract T createPacket(
+ byte[] buf, int off, int len, Object context);
+
+ /**
+ * A simple interface to handle packets.
+ * @param the type of the packets.
+ */
+ public interface PacketHandler
+ {
+ /**
+ * Does something with a packet.
+ * @param pkt the packet to do something with.
+ * @return {@code true} if the operation was successful, and
+ * {@code false} otherwise.
+ */
+ boolean handlePacket(T pkt);
+ }
+}
diff --git a/src/main/java/org/ice4j/util/QueueStatistics.java b/src/main/java/org/ice4j/util/QueueStatistics.java
new file mode 100644
index 0000000..7504ebf
--- /dev/null
+++ b/src/main/java/org/ice4j/util/QueueStatistics.java
@@ -0,0 +1,113 @@
+package org.ice4j.util;
+
+import java.util.logging.*;
+
+public class QueueStatistics
+{
+ /**
+ * The scale to use for {@link RateStatistics}. This makes their output in
+ * units (e.g. packets) per second.
+ */
+ private static final int SCALE = 1000;
+
+ /**
+ * The interval (in number of calls to {@link #add(long)} or
+ * {@link #remove(long)}) at which the gathered statistics will be printed.
+ */
+ private static final int DEFAULT_PRINT_INTERVAL = 500;
+
+ /**
+ * Calculate the average rate of addition of packets in a 200ms window.
+ */
+ private final RateStatistics addRateStatistics = new RateStatistics(200, SCALE);
+
+ /**
+ * Calculate the average rate of removal of packets in a 200ms window.
+ */
+ private final RateStatistics removeRateStatistics = new RateStatistics(200, SCALE);
+
+ /**
+ * The {@link Logger} instance used for logging output.
+ */
+ private final Logger logger;
+
+ private int head = 0;
+ private int size = 0;
+ private int[] sizes = new int[DEFAULT_PRINT_INTERVAL];
+ private long[] timestamps = new long[DEFAULT_PRINT_INTERVAL];
+ private long[] addRates = new long[DEFAULT_PRINT_INTERVAL];
+ private long[] removeRates = new long[DEFAULT_PRINT_INTERVAL];
+ private int[] totalPacketsAddedHistory = new int[DEFAULT_PRINT_INTERVAL];
+ private int totalPacketsAdded = 0;
+ private String logHeader;
+
+ /**
+ * Initializes a new {@link QueueStatistics} instance.
+ * @param id
+ */
+ public QueueStatistics(String id)
+ {
+ logger = Logger.getLogger("QueueStatistics-" + id);
+ logHeader = "QueueStatistics-" + id + ": ";
+
+ // We let the users of this class decide whether to enable logging (by
+ // creating a QueueStatistic instance) or not.
+ logger.setLevel(Level.ALL);
+ }
+
+ /**
+ * Registers the addition of a packet to the corresponding queue.
+ * @param now the time (in milliseconds since the epoch) at which the
+ * packet was added.
+ */
+ public synchronized void add(long now)
+ {
+ addRateStatistics.update(1, now);
+ size++;
+ totalPacketsAdded++;
+ update(now);
+ }
+
+ /**
+ * Registers the removal of a packet from the corresponding queue.
+ * @param now the time (in milliseconds since the epoch) at which the
+ * packet was removed.
+ */
+ public synchronized void remove(long now)
+ {
+ removeRateStatistics.update(1, now);
+ size--;
+ update(now);
+ }
+
+ private synchronized void update(long now)
+ {
+ if (head == sizes.length)
+ {
+ print();
+ head = 0;
+ }
+
+ sizes[head] = size;
+ timestamps[head] = now;
+ addRates[head] = addRateStatistics.getRate(now);
+ removeRates[head] = removeRateStatistics.getRate(now);
+ totalPacketsAddedHistory[head] = totalPacketsAdded;
+ head++;
+ }
+
+ private void print()
+ {
+ StringBuilder s = new StringBuilder();
+ for (int i =0; i8*1000 to go to bits/s.
+ */
+ public RateStatistics(int windowSizeMs, float scale)
+ {
+ buckets = new long[windowSizeMs + 1]; // N ms in (N+1) buckets.
+ this.scale = scale / (buckets.length - 1);
+ }
+
+ private void eraseOld(long nowMs)
+ {
+ long newOldestTime = nowMs - buckets.length + 1;
+
+ if (newOldestTime <= oldestTime)
+ return;
+
+ while (oldestTime < newOldestTime)
+ {
+ long countInOldestBucket = buckets[oldestIndex];
+
+ accumulatedCount -= countInOldestBucket;
+ buckets[oldestIndex] = 0L;
+ if (++oldestIndex >= buckets.length)
+ {
+ oldestIndex = 0;
+ }
+ ++oldestTime;
+ if (accumulatedCount == 0L)
+ {
+ // This guarantees we go through all the buckets at most once,
+ // even if newOldestTime is far greater than oldestTime.
+ break;
+ }
+ }
+ oldestTime = newOldestTime;
+ }
+
+ public long getRate(long nowMs)
+ {
+ eraseOld(nowMs);
+ return (long) (accumulatedCount * scale + 0.5F);
+ }
+
+ public void update(int count, long nowMs)
+ {
+ if (nowMs < oldestTime) // Too old data is ignored.
+ return;
+
+ eraseOld(nowMs);
+
+ int nowOffset = (int) (nowMs - oldestTime);
+ int index = oldestIndex + nowOffset;
+
+ if (index >= buckets.length)
+ index -= buckets.length;
+ buckets[index] += count;
+ accumulatedCount += count;
+ }
+}