/* * ***************************************************************************** * Copyright (C) 2014-2026 Dennis Sheirer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see * **************************************************************************** */ package io.github.dsheirer.util; import io.github.dsheirer.controller.NamingThreadFactory; import io.github.dsheirer.sample.Listener; import io.github.dsheirer.source.heartbeat.HeartbeatManager; import java.util.ArrayList; import java.util.List; import java.util.concurrent.BlockingQueue; import java.util.concurrent.Executors; import java.util.concurrent.LinkedBlockingQueue; import java.util.concurrent.LinkedTransferQueue; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.ScheduledFuture; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicLong; import java.util.function.ToLongFunction; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * Threaded scheduled processor for receiving elements from a separate producer thread and forwarding those buffers to a * registered listener on this consumer/dispatcher thread. Internally uses a single-thread thread pool to effect a * timer-based interval for processing to avoid excessive context switching inherent in a blocking queue. Sizes the * thread pool to a single thread to ensure Garbage Collector can efficiently clean objects created on the thread. */ public class Dispatcher implements Listener { private final static Logger mLog = LoggerFactory.getLogger(Dispatcher.class); private static final long OVERFLOW_LOG_INTERVAL_MILLISECONDS = 10000; private final BlockingQueue mQueue; private Listener mListener; private final AtomicBoolean mRunning = new AtomicBoolean(); private String mThreadName; private ScheduledExecutorService mExecutorService; private ScheduledFuture mScheduledFuture; private final long mInterval; private HeartbeatManager mHeartbeatManager; private long mDroppedCount = 0; private long mLastOverflowLogTimestamp = 0; private final ToLongFunction mWeigher; private volatile long mMaximumQueuedWeight = Long.MAX_VALUE; private final AtomicLong mQueuedWeight = new AtomicLong(); /** * Constructs an instance of a Dispatcher with integrated heartbeat support. * @param threadName to name the dispatcher thread * @param interval for processing each batch in milliseconds. * @param heartbeatManager to receive a heartbeat command at each processing interval. */ public Dispatcher(String threadName, long interval, HeartbeatManager heartbeatManager) { this(threadName, interval); mHeartbeatManager = heartbeatManager; } /** * Constructs an instance of a bounded Dispatcher with integrated heartbeat support. * @param threadName to name the dispatcher thread * @param interval for processing each batch in milliseconds. * @param heartbeatManager to receive a heartbeat command at each processing interval. * @param maximumQueueSize for queued elements. Elements received while the queue is full are dropped. */ public Dispatcher(String threadName, long interval, HeartbeatManager heartbeatManager, int maximumQueueSize) { this(threadName, interval, maximumQueueSize); mHeartbeatManager = heartbeatManager; } /** * Constructs an instance with an unbounded queue. * @param threadName to name the dispatcher thread * @param interval for processing each batch in milliseconds. */ public Dispatcher(String threadName, long interval) { mThreadName = threadName; mInterval = interval; mQueue = new LinkedTransferQueue<>(); mWeigher = null; } /** * Constructs a bounded instance. * @param threadName to name the dispatcher thread * @param interval for processing each batch in milliseconds. * @param maximumQueueSize for queued elements. Elements received while the queue is full are dropped. */ public Dispatcher(String threadName, long interval, int maximumQueueSize) { mThreadName = threadName; mInterval = interval; mQueue = new LinkedBlockingQueue<>(maximumQueueSize); mWeigher = null; } /** * Constructs an instance that is bounded by the total weight of the queued elements instead of the element count, * for when element sizes vary widely, for example sample buffers from different tuners. An element is dropped * when adding it would exceed the maximum weight, except when nothing is queued, so that an element heavier than * the maximum is still delivered. Elements count toward the weight until the listener has processed them. * * @param threadName to name the dispatcher thread * @param interval for processing each batch in milliseconds. * @param weigher to calculate the weight of each element, for example a sample count. * @param maximumQueuedWeight for the queued elements. */ public Dispatcher(String threadName, long interval, ToLongFunction weigher, long maximumQueuedWeight) { if(weigher == null) { throw new IllegalArgumentException("Weigher cannot be null"); } mThreadName = threadName; mInterval = interval; mQueue = new LinkedTransferQueue<>(); mWeigher = weigher; setMaximumQueuedWeight(maximumQueuedWeight); } /** * Sets the maximum total weight of the queued elements, for a dispatcher that was constructed with a weigher. * @param maximumQueuedWeight for the queued elements. */ public void setMaximumQueuedWeight(long maximumQueuedWeight) { if(maximumQueuedWeight <= 0) { throw new IllegalArgumentException("Maximum queued weight must be positive: " + maximumQueuedWeight); } mMaximumQueuedWeight = maximumQueuedWeight; } /** * Sets the thread name. If this dispatcher is already started, this has no effect. * @param threadName to use for this dispatcher. */ public void setThreadName(String threadName) { mThreadName = threadName; } /** * Sets or changes the listener to receive buffers from this processor. * @param listener to receive buffers */ public void setListener(Listener listener) { mListener = listener; } /** * Primary input method for adding buffers to this processor. Note: incoming buffers will be ignored if this * processor is in a stopped state. You must invoke start() to allow incoming buffers and initiate buffer * processing. If this processor has a bounded queue and the queue is full, the incoming buffer is dropped. * * @param e to enqueue for distribution to a registered listener */ public void receive(E e) { offer(e); } /** * Adds the element to this processor's queue, for when the caller has to take action on an element that isn't * accepted. * * @param e to enqueue for distribution to a registered listener * @return true if the element was queued, or false if this processor is stopped or a bounded queue is full. */ public boolean offer(E e) { if(!mRunning.get()) { return false; } boolean queued; if(mWeigher != null) { long weight = mWeigher.applyAsLong(e); long queuedWeight = mQueuedWeight.addAndGet(weight); if(queuedWeight > mMaximumQueuedWeight && queuedWeight > weight) { mQueuedWeight.addAndGet(-weight); queued = false; } else { queued = mQueue.offer(e); } } else { queued = mQueue.offer(e); } if(!queued) { mDroppedCount++; long now = System.currentTimeMillis(); if(now - mLastOverflowLogTimestamp >= OVERFLOW_LOG_INTERVAL_MILLISECONDS) { mLog.warn("Dispatcher [" + mThreadName + "] queue is full, consumer is not keeping up - dropped [" + mDroppedCount + "] elements"); mLastOverflowLogTimestamp = now; mDroppedCount = 0; } } return queued; } /** * Starts this buffer processor and allows queuing of incoming buffers. */ public void start() { if(mRunning.compareAndSet(false, true)) { if(mScheduledFuture != null) { //Note: this has to be false because downstream implementations may have acquired locks and they must //be able to release those locks or we'll get a deadlock situation. mScheduledFuture.cancel(false); } if(mExecutorService != null) { mExecutorService.shutdown(); mExecutorService = null; } mQueue.clear(); mQueuedWeight.set(0); mExecutorService = Executors.newSingleThreadScheduledExecutor(new NamingThreadFactory(mThreadName)); Runnable r = (mHeartbeatManager != null ? new ProcessorWithHeartbeat() : new Processor()); mScheduledFuture = mExecutorService.scheduleAtFixedRate(r, 0, mInterval, TimeUnit.MILLISECONDS); } } /** * Stops this buffer processor and waits up to two seconds for the processing thread to terminate. */ public void stop() { if(mRunning.compareAndSet(true, false)) { if(mScheduledFuture != null) { //Note: this has to be false because downstream implementations may have acquired locks and they must //be able to release those locks or we'll get a deadlock situation. mScheduledFuture.cancel(false); mScheduledFuture = null; mQueue.clear(); mQueuedWeight.set(0); } if(mExecutorService != null) { mExecutorService.shutdown(); mExecutorService = null; } } } /** * Stops this buffer processor and flushes the queue to the listener */ public void flushAndStop() { if(mRunning.compareAndSet(true, false)) { if(mScheduledFuture != null) { //Note: this has to be false because downstream implementations may have acquired locks and they must //be able to release those locks or we'll get a deadlock situation. mScheduledFuture.cancel(false); mScheduledFuture = null; } if(mExecutorService != null) { mExecutorService.shutdown(); mExecutorService = null; } List elements = new ArrayList<>(); mQueue.drainTo(elements); for(E element: elements) { if(mListener != null) { try { mListener.receive(element); } catch(Throwable t) { mLog.error("Error while flusing and dispatching element [" + element.getClass() + "] to listener [" + mListener.getClass() + "]", t); } } release(element); } } } /** * Indicates if this processor is currently running */ public boolean isRunning() { return mRunning.get(); } /** * Processes elements from the queue. Note: this should only be invoked on the Processor thread. */ private void process() { List elements = new ArrayList<>(); mQueue.drainTo(elements); for(E element: elements) { if(mRunning.get() && mListener != null) { try { mListener.receive(element); } catch(Throwable t) { mLog.error("Error while dispatching element [" + element.getClass() + "] to listener [" + mListener.getClass() + "]", t); } } release(element); } } /** * Removes the weight of a dequeued element from the queued weight, once the element is processed. */ private void release(E element) { if(mWeigher != null) { mQueuedWeight.addAndGet(-mWeigher.applyAsLong(element)); } } /** * Processor to service the buffer queue and distribute the buffers to the registered listener */ class Processor implements Runnable { private final AtomicBoolean mRunning = new AtomicBoolean(); @Override public void run() { if(mRunning.compareAndSet(false, true)) { process(); mRunning.set(false); } } } /** * Processor to service the buffer queue and distribute the buffers to the registered listener. Includes a * support for commanding a heart beat with each processing interval. */ class ProcessorWithHeartbeat implements Runnable { private final AtomicBoolean mRunning = new AtomicBoolean(); @Override public void run() { if(mRunning.compareAndSet(false, true)) { process(); try { mHeartbeatManager.broadcast(); } catch(Throwable t) { mLog.error("Error broadcasting heartbeat during Dispatcher processing interval", t); } mRunning.set(false); } } } }