Class PeriodicPriorityQueue

java.lang.Object
org.wpilib.internal.PeriodicPriorityQueue
public class PeriodicPriorityQueue extends Object
A priority queue for scheduling periodic callbacks based on their next execution time.

This class manages a collection of periodic callbacks that execute at specified intervals. Callbacks are scheduled using monotonic timestamps and automatically rescheduled after execution to maintain their periodic behavior. The queue uses a priority heap to efficiently determine the next callback to execute.

This is an internal scheduling primitive used by robot frameworks like TimedRobot.

  • Constructor Details

  • Method Details

    • add

      public PeriodicPriorityQueue.Callback add(Runnable func, long timestamp, double periodSeconds, double offsetSeconds)
      Adds a periodic callback to the queue with a specified start time.
      Parameters:
      func - The function to call periodically.
      timestamp - The common starting point for callback scheduling in monotonic timestamp microseconds.
      periodSeconds - The callback period in seconds.
      offsetSeconds - The offset from the common starting time in seconds.
      Returns:
      the callback object

    • add

      public PeriodicPriorityQueue.Callback add(Runnable func, long timestamp, double periodSeconds)
      Adds a periodic callback to the queue with a specified start time.
      Parameters:
      func - The function to call periodically.
      timestamp - The common starting point for callback scheduling in monotonic timestamp microseconds.
      periodSeconds - The callback period in seconds.
      Returns:
      the callback object

    • add

      public PeriodicPriorityQueue.Callback add(Runnable func, double periodSeconds, double offsetSeconds)
      Adds a periodic callback to the queue, starting from the current monotonic time.
      Parameters:
      func - The function to call periodically.
      periodSeconds - The callback period in seconds.
      offsetSeconds - The offset from the current monotonic time in seconds.
      Returns:
      the callback object

    • add

      public PeriodicPriorityQueue.Callback add(Runnable func, double periodSeconds)
      Adds a periodic callback to the queue, starting from the current monotonic time.
      Parameters:
      func - The function to call periodically.
      periodSeconds - The callback period in seconds.
      Returns:
      the callback object

    • add

      public void add(PeriodicPriorityQueue.Callback callback)
      Adds a pre-constructed callback to the queue.
      Parameters:
      callback - The callback to add.

    • addAll

      public void addAll(Collection<PeriodicPriorityQueue.Callback> callbacks)
      Adds multiple callbacks to the queue.
      Parameters:
      callbacks - The collection of callbacks to add.

    • remove

      public void remove(Runnable func)
      Removes all callbacks associated with the given function.
      Parameters:
      func - The function whose callbacks should be removed.

    • remove

      public void remove(PeriodicPriorityQueue.Callback callback)
      Removes a specific callback from the queue.
      Parameters:
      callback - The callback to remove.

    • removeAll

      public void removeAll(Collection<PeriodicPriorityQueue.Callback> callbacks)
      Removes multiple callbacks from the queue.
      Parameters:
      callbacks - The collection of callbacks to remove.

    • clear

      public void clear()
      Removes all callbacks from the queue.

    • runCallbacks

      public boolean runCallbacks(int notifier)
      Executes all callbacks that are due, then waits for the next callback's scheduled time.

      This method performs the following steps:

      1. Retrieves the callback with the earliest expiration time from the queue
      2. Sets a hardware notifier alarm to wait until that callback's expiration time
      3. Blocks until the notifier signals or is interrupted
      4. Executes the callback and reschedules it for its next period
      5. Processes any additional callbacks that have become due during execution

      When rescheduling callbacks, this method automatically compensates for execution delays by advancing the expiration time by the number of full periods that have elapsed, ensuring callbacks maintain their scheduled phase over time.

      Parameters:
      notifier - The HAL notifier handle to use for timing.
      Returns:
      whether the notifier was signaled before the timeout.
      Throws:
      IllegalStateException - if the queue is empty when this method is called.

    • getLoopStartTime

      public long getLoopStartTime()
      Return the system clock time in microseconds for the start of the current periodic loop. This is in the same time base as Timer.getMonotonicTimeStamp(), but is stable through a loop. It is updated at the beginning of every periodic callback (including the normal periodic loop).
      Returns:
      Robot running time in microseconds, as of the start of the current periodic function.