com.badlogic.gdx.ai.sched

Class LoadBalancingScheduler

java.lang.Object

com.badlogic.gdx.ai.sched.SchedulerBase<SchedulerBase.SchedulableRecord>

com.badlogic.gdx.ai.sched.LoadBalancingScheduler

All Implemented Interfaces:

Schedulable, Scheduler

public class LoadBalancingScheduler
extends SchedulerBase<SchedulerBase.SchedulableRecord>

A LoadBalancingScheduler understands the time it has to run and distributes this time among the tasks that need to be run. This scheduler splits the time it is given according to the number of tasks that must be run on this frame. To adjust for small errors in the running time of tasks, this scheduler recalculates the time it has left after each task is run. This way an overrunning task will reduce the time that is given to others run in the same frame.

The scheduler takes tasks, each one having a frequency and a phase that determine when it should be run.

• Frequency: On each time frame, the scheduler is called to manage the whole AI budget. It decides which tasks need to be run and calls them. This is done by keeping count of the number of frames passed. This is incremented each time the scheduler is called. It is easy to test if each task should be run by checking if the frame count is evenly divisible by the frequency. On its own, this approach suffers from clumping: some frames with no tasks being run, and other frames with several tasks sharing the budget. Picking frequencies that are relatively prime makes the clash points less frequent but doesn't eliminate them. To solve the problem, we use the phase.
• Phase: The phase doesn't change the frequency but offsets when the task will be called. However, calculating good phase values to avoid spikes can be difficult. It is not intuitively clear whether a particular set of frequency and phase values will lead to a regular spike or not. That's why this scheduler supports automatic phasing. When a new task is added to the scheduler, with a frequency of f, we perform a dry run of the scheduler for a fixed number of frames into the future. Rather than executing tasks in this dry run, we simply count how many would be executed. We find the frame with the least number of running tasks. The phase value for the task is set to the number of frames ahead at which this minimum occurs. The fixed number of frames is normally a manually set value found by experimentation. Ideally, it would be the least common multiple (LCM) of all the frequency values used in the scheduler, see ArithmeticUtils.lcmPositive(int, int). Typically, however, this is a large number and would slow the algorithm unnecessarily (for frequencies of 2, 3, 5, 7, and 11, for example, we have an LCM of 2310). Despite being a good approach in practice, it has a theoretical chance that it will still produce heavy spikes, if the lookahead isn't at least as large as the size of the LCM.

Nested Class Summary

Nested classes/interfaces inherited from class com.badlogic.gdx.ai.sched.SchedulerBase

SchedulerBase.SchedulableRecord

Field Summary

Fields

Modifier and Type	Field and Description
protected int	frame The current frame number

Fields inherited from class com.badlogic.gdx.ai.sched.SchedulerBase

dryRunFrames, phaseCounters, runList, schedulableRecords

Constructor Summary

Constructors

Constructor and Description
LoadBalancingScheduler(int dryRunFrames) Creates a LoadBalancingScheduler.

Method Summary

Modifier and Type	Method and Description
void	add(Schedulable schedulable, int frequency, int phase) Adds the schedulable to the list using the given frequency and phase
void	addWithAutomaticPhasing(Schedulable schedulable, int frequency) Adds the schedulable to the list using the given frequency and a phase calculated by a dry run of the scheduler.
void	run(long timeToRun) Executes scheduled tasks based on their frequency and phase.

Methods inherited from class com.badlogic.gdx.ai.sched.SchedulerBase

calculatePhase

Methods inherited from class java.lang.Object

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

Field Detail

frame

protected int frame

The current frame number

Constructor Detail

LoadBalancingScheduler

public LoadBalancingScheduler(int dryRunFrames)

Creates a LoadBalancingScheduler.

Parameters:

dryRunFrames - number of frames simulated by the dry run to calculate the phase when adding a schedulable via addWithAutomaticPhasing(Schedulable, int)

Method Detail

addWithAutomaticPhasing

public void addWithAutomaticPhasing(Schedulable schedulable,
                                    int frequency)

Adds the schedulable to the list using the given frequency and a phase calculated by a dry run of the scheduler.

Parameters:

schedulable - the task to schedule

frequency - the frequency

add

public void add(Schedulable schedulable,
                int frequency,
                int phase)

Description copied from interface: Scheduler

Adds the schedulable to the list using the given frequency and phase

Parameters:

schedulable - the task to schedule

frequency - the frequency

phase - the phase

run

public void run(long timeToRun)

Executes scheduled tasks based on their frequency and phase. This method must be called once per frame.

Parameters:

timeToRun - the maximum time in nanoseconds this scheduler should run on the current frame.