com.lhkbob.entreri.task

Class Scheduler

java.lang.Object

com.lhkbob.entreri.task.Scheduler

public class Scheduler
extends Object

Scheduler coordinates the multi-threaded execution of jobs that process an EntitySystem. It is the factory that creates jobs and contains convenience methods to schedule the execution of jobs.

As an example, here's how you can set up a 'rendering' job, assuming that all tasks necessary to perform rendering are in an array called renderTasks:

 Job renderJob = system.getScheduler().createJob("rendering", renderTasks);
 ExecutorService service = system.getScheduler().runEvery(1.0 / 60.0, renderJob);

 // ... perform game logic, and wait for exit request
 service.shutdown();
 

Author:

Michael Ludwig

Constructor Summary

Constructors

Constructor and Description
Scheduler(EntitySystem system) Create a new Scheduler for the given EntitySystem.

Method Summary

Methods

Modifier and Type	Method and Description
Job	createJob(String name, Task... tasks) Create a new job with the given name, that will execute the provided tasks in order.
EntitySystem	getEntitySystem()
ExecutorService	runContinuously(Job job) Create an ExecutorService that is configured to execute the given job back to back as fast as the job executes.
ExecutorService	runEvery(double dt, Job job) Create an ExecutorService that is configured to execute the given job every dt seconds.
void	runOnCurrentThread(Job job) Execute the given job on the current thread.
void	runOnSeparateThread(Job job) Execute the given job once on a new thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scheduler

public Scheduler(EntitySystem system)

Create a new Scheduler for the given EntitySystem. It is recommended to use the scheduler provided by the system. If multiple schedulers exist for the same entity system, they cannot guarantee thread safety between each other, only within their own jobs.

Parameters:

system - The EntitySystem accessed by jobs created by this scheduler

Throws:

NullPointerException - if system is null

See Also:

EntitySystem.getScheduler()

Method Detail

getEntitySystem

public EntitySystem getEntitySystem()

Returns:

The EntitySystem accessed by this scheduler

createJob

public Job createJob(String name,
            Task... tasks)

Create a new job with the given name, that will execute the provided tasks in order.

Parameters:

name - The name of the new job

tasks - The tasks of the job

Returns:

The new job

Throws:

NullPointerException - if name is null, tasks is null or contains null elements

runOnCurrentThread

public void runOnCurrentThread(Job job)

Execute the given job on the current thread. This will not return until after the job has completed invoking all of its tasks, and any subsequently produced tasks.

This is a convenience for invoking Job.run(), and exists primarily to parallel the other runX(Job) methods.

Parameters:

job - The job to run

Throws:

NullPointerException - if job is null

IllegalArgumentException - if job was not created by this scheduler

runOnSeparateThread

public void runOnSeparateThread(Job job)

Execute the given job once on a new thread. This will create a new thread that will invoke the job once and then terminate once the job returns. This method will return after the thread starts and will not block the calling thread while the job is executed.

This should be used as a convenience to invoke one-off jobs that should not block a performance sensitive thread.

Parameters:

job - The job to run

Throws:

NullPointerException - if job is null

IllegalArgumentException - if job was not created by this scheduler

runEvery

public ExecutorService runEvery(double dt,
                       Job job)

Create an ExecutorService that is configured to execute the given job every dt seconds. Assuming that the job terminates in under dt seconds, it will not be invoked until dt seconds after it was first started.

To schedule a rendering job to run at 60 FPS, you could call runEvery(1.0 / 60.0, renderJob).

The returned ExecutorService should have its shutdown() method called when the job no longer needs to be invoked. Scheduling timing is undefined if new Runnables or Callables are submitted to the returned service.

Parameters:

dt - The amount of time between the start of each job execution

job - The job to be repeatedly executed

Returns:

An unconfigurable executor service that performs the scheduling, and owns the execution thread

Throws:

NullPointerException - if job is null

IllegalArgumentException - if job was not created by this scheduler, or if dt is negative

runContinuously

public ExecutorService runContinuously(Job job)

Create an ExecutorService that is configured to execute the given job back to back as fast as the job executes.

This effectively performs the following logic on a separate thread:

 while (true) {
     job.run();
 }
 

The returned ExecutorService should have its shutdown() method called when the job no longer needs to be invoked. Scheduling timing is undefined if new Runnables or Callables are submitted to the returned service.

Parameters:

job - The job to be repeatedly executed

Returns:

An unconfigurable executor service that performs the scheduling, and owns the execution thread

Throws:

NullPointerException - if job is null

IllegalArgumentException - if job was not created by this scheduler