Package com.tccc.kos.commons.util.concurrent

Class TriggeredCallback

java.lang.Object
com.tccc.kos.commons.util.concurrent.BaseCallback
com.tccc.kos.commons.util.concurrent.TriggeredCallback
public class TriggeredCallback extends BaseCallback
Class that triggers a callback after the configured delay. Once triggered, any additional triggers during the delay period are ignored. This is primarily used as a mechanism to aggregate events into a single delayed callback without having to manually manage timers. This implementation guarantees that the callback is never called concurrently, even if called inline. It also guarantees that every trigger is ultimately followed by a callback, even if a trigger occurs while a callback is in progress.

This implementation supports delay variance. This allows a variance range to be set in addition to the delay. This means that rather than performing the callback exactly after the specified delay, a random delay within the variance window is used. To use variances, adjust the minVariance and/or maxVariance values. These are percentages specified as a decimal value (i.e. 1.0 == 100%). To specify a delay in the range of 75-100% of the configured delay value, set minVariance to 0.75 and maxVariance to 1.0. To specify a delay in the range of 75-125%, use 0.75 and 1.25, respectively.

Since:
1.0
Version:
2022-10-28

  • Constructor Details

    • TriggeredCallback

      public TriggeredCallback(int delay, Runnable callback)
      Constructs a triggered callback with the specified delay and callback method. Its internal timer is not started until trigger() is called.

  • Method Details

    • getDelay

      public int getDelay()
      Returns the timer's delay.
      Returns:
      the delay time (msec)

    • setDelay

      public void setDelay(int delay)
      Sets a new delay value for the timer.
      • If the timer is already running, then the current delay is changed using the new value minus how much time has already elapsed.
      • If the timer is not running, then only the delay value is updated; the timer is not started.
      Parameters:
      delay - the new delay value (msec)

    • getMinVariance

      public double getMinVariance()
      Retrieves the minimum delay variance.
      Returns:
      the min delay variance

    • setMinVariance

      public TriggeredCallback setMinVariance(double minVariance)
      Sets the minimum delay variance.
      Parameters:
      minVariance - the min variance, any non-negative number

    • getMaxVariance

      public double getMaxVariance()
      Retrieves the maximum delay variance.
      Returns:
      the max delay variance

    • setMaxVariance

      public TriggeredCallback setMaxVariance(double maxVariance)
      Sets the maximum delay variance.
      Parameters:
      maxVariance - the max variance, any non-negative number

    • trigger

      public void trigger()
      Triggers a callback.
      • If the timer is already running, then no action is taken.
      • If the timer is not running, then it is started using the currently defined delay value.