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; + } +}