PeriodicPriorityQueue

class wpilib.PeriodicPriorityQueue

Bases: pybind11_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 FPGA 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.

class Callback(*args, **kwargs)

Bases: pybind11_object

A periodic callback with scheduling metadata.

Each callback tracks its target function, period, and next expiration time. After execution, the expiration time is automatically advanced by full periods to maintain precise timing even when execution is delayed.

Overloaded function.

  1. __init__(self: wpilib._wpilib.PeriodicPriorityQueue.Callback, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: datetime.timedelta, offset: datetime.timedelta) -> None

Construct a callback container.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling.

  • period – The period at which to run the callback.

  • offset – The offset from the common starting time.

  1. __init__(self: wpilib._wpilib.PeriodicPriorityQueue.Callback, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: wpimath.units.seconds, offset: wpimath.units.seconds) -> None

Construct a callback container using units-based period and offset.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling.

  • period – The period at which to run the callback.

  • offset – The offset from the common starting time.

  1. __init__(self: wpilib._wpilib.PeriodicPriorityQueue.Callback, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: wpimath.units.seconds) -> None

Construct a callback container using units-based period.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling.

  • period – The period at which to run the callback.

add(*args, **kwargs)

Overloaded function.

  1. add(self: wpilib._wpilib.PeriodicPriorityQueue, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: datetime.timedelta) -> None

Adds a periodic callback to the queue.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling.

  • period – The period at which to run the callback.

  1. add(self: wpilib._wpilib.PeriodicPriorityQueue, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: datetime.timedelta, offset: datetime.timedelta) -> None

Adds a periodic callback to the queue.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling.

  • period – The period at which to run the callback.

  • offset – The offset from the common starting time.

  1. add(self: wpilib._wpilib.PeriodicPriorityQueue, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: wpimath.units.seconds) -> None

Adds a periodic callback to the queue.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling in FPGA timestamp microseconds.

  • period – The period at which to run the callback.

  1. add(self: wpilib._wpilib.PeriodicPriorityQueue, func: collections.abc.Callable[[], None], startTime: datetime.timedelta, period: wpimath.units.seconds, offset: wpimath.units.seconds) -> None

Adds a periodic callback to the queue.

Parameters:

  • func – The callback to run.

  • startTime – The common starting point for all callback scheduling in FPGA timestamp microseconds.

  • period – The period at which to run the callback.

  • offset – The offset from the common starting time.

  1. add(self: wpilib._wpilib.PeriodicPriorityQueue, callback: wpilib._wpilib.PeriodicPriorityQueue.Callback) -> None

Adds a pre-constructed callback to the queue.

Parameters:

callback – The callback to add.

clear() → None

Removes all callbacks from the queue.

getLoopStartTime() → wpimath.units.microseconds

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.

remove(callback: wpilib._wpilib.PeriodicPriorityQueue.Callback) → bool

Removes a specific callback from the queue.

Parameters:

callback – The callback to remove.

Returns:

true if the callback was found and removed, false otherwise.

runCallbacks(notifier: SupportsInt | SupportsIndex) → bool

Executes all callbacks that are due, then waits for the next callback’s scheduled time.

This method performs the following steps: -# Retrieves the callback with the earliest expiration time from the queue -# Sets a hardware notifier alarm to wait until that callback’s expiration time -# Blocks until the notifier signals or is interrupted -# Executes the callback and reschedules it for its next period -# 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:

false if the notifier was destroyed (loop should exit), true otherwise.