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

Class PushPullCallback

java.lang.Object
com.tccc.kos.commons.util.concurrent.BaseCallback
com.tccc.kos.commons.util.concurrent.PushPullCallback
public class PushPullCallback extends BaseCallback
Class used to schedule a callback after a specified delay, but can be used in three different ways:
  • Using start(), the timer acts like a typical timer that runs for the specified delay. If a timer is already running, it is and then a new timer is started with the specified delay. This is the simplest way to use this callback and has standard start / cancel semantics.
  • Using push(), this callback is used like a dead-man-switch, in that every call to push() extends the timeout of the existing timer. This is useful for applications such as monitoring a keep-alive event, as each keep-alive simply pushes the timer out and the callback triggers when there are no more events.

    Pushing a timer never makes the current timeout shorter. If a timer is already in effect and the timer is pushed, the new value is only used if the end time of the push is beyond the end time of the existing timer. This allows for timer policies where certain events push the timer a small amount, while other events push the timer large amounts, but the timer always uses the latest end time among all the push calls.

  • Using pull(), this callback can be used as a priority timer. The opposite of push(), calls to pull() only make the timer shorter until it triggers. This is useful for combining lazy and priority events. For example, an event occurs that should trigger a lazy operation, so pull() is used with a large timeout which starts the timer. Another higher priority event occurs which requires a faster response from the timer, so pull() is called with a shorter delay, which pulls the timeout of the timer in so that it triggers quicker. Another lazy event occurs which calls pull() with a long delay, but it has no effect because pull() can only shorten a timeout.
In general, these three modes of operation are distinct: mixing calls to start(), push() and pull() typically don't make sense, but there is no restriction on mixing these calls.

This implementation guarantees that the callback is never be called concurrently, even if the timer is rebuilt and triggered during an existing callback, or even if the timer if flushed.

Since:
1.0
Version:
2022-10-13

  • Constructor Summary

    Constructors
    Constructor
    Description
    PushPullCallback(Runnable callback)
    Creates a push/pull callback with the specified callback method.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    pull(long delay, boolean start)
    Adjusts an existing timer using the specified delay , optionally starting the timer (if needed) when the start flag is true.
    void
    push(long delay, boolean start)
    Adjusts an existing timer using the specified delay , optionally starting the timer (if needed) when the start flag is true.
    void
    start(long delay)
    Triggers a callback after the specified delay.

    Methods inherited from class com.tccc.kos.commons.util.concurrent.BaseCallback

    cancel, flush, flushInline, force, forceInline, getCallback, getWaitTime, isRunning, isStopped

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PushPullCallback

      public PushPullCallback(Runnable callback)
      Creates a push/pull callback with the specified callback method. Its internal timer is not started until either start() , push() or pull() is called.

  • Method Details

    • start

      public void start(long delay)
      Triggers a callback after the specified delay. If a timer is already running, it is cancelled and then restarted.
      Parameters:
      delay - amount of time to delay before the callback is called (msec)

    • push

      public void push(long delay, boolean start)
      Adjusts an existing timer using the specified delay , optionally starting the timer (if needed) when the start flag is true. This method is used to (potentionally) push the callback further into the future.
      • If the timer is currently running, the end time using the specified delay is computed and if greater than the current end time, the timer is adjusted to use the new end time.
      • If the timer is not running and the start flag is true, the timer will be started with the specified delay.
      This allows different delays to be used (such as different delays for different event priorities) and the end time is always the longest of all the calls.
      Parameters:
      delay - amount of time to delay before the callback is called (msec)
      start - if true, start the timer if not running

    • pull

      public void pull(long delay, boolean start)
      Adjusts an existing timer using the specified delay , optionally starting the timer (if needed) when the start flag is true. This method is used to (potentially) pull the callback closer to the present time.
      • If the timer is currently running, the end time using the specified delay is computed and if less than the current end time, the timer is adjusted to use the new end time.
      • If the timer is not running and the start flag is true, the timer will be started with the specified delay.
      This allows different delays to be used (such as different delays for different event priorities) and the end time is always the shortest of all the calls.
      Parameters:
      delay - amount of time to delay before the callback is called (msec)
      start - if true, start the timer if not running