com.sun.sgs.kernel
Interface TaskScheduler

public interface TaskScheduler

This interface is used to run tasks that may take an arbitrarily long time to complete, but are expected to complete eventually. These tasks may be scheduled to run immediately or after some delay, possibly re-executing at regular intervals.

Based on an implementation's policy, a task and its owner, that task may not be accepted for execution. In this case TaskRejectedException is thrown. To ensure that a task will be accepted methods are provided to get a TaskReservation. This is especially useful for Service methods working within a transaction that need to ensure that a task will be accepted before they can commit.

Note that, because the tasks submitted through this interface may run any length of time, there are no guarantees about when a given task will start. If a task is scheduled to run immediately, or at some point in the future, then this means that the scheduler will try to acquire resources to run the task at that point. It may still be some indefinite length of time before the task can actually be run.

Method Summary

TaskQueue	createTaskQueue() Creates a new TaskQueue to use in scheduling dependent tasks.
TaskReservation	reserveTask(KernelRunnable task, Identity owner) Reserves the ability to run the given task.
TaskReservation	reserveTask(KernelRunnable task, Identity owner, long startTime) Reserves the ability to run the given task at a specified point in the future.
RecurringTaskHandle	scheduleRecurringTask(KernelRunnable task, Identity owner, long startTime, long period) Schedules a task to start running at a specified point in the future, and continuing running on a regular period starting from that initial point.
void	scheduleTask(KernelRunnable task, Identity owner) Schedules a task to run as soon as possible based on the specific scheduler implementation.
void	scheduleTask(KernelRunnable task, Identity owner, long startTime) Schedules a task to run at a specified point in the future.

Method Detail

reserveTask

TaskReservation reserveTask(KernelRunnable task,
                            Identity owner)

Reserves the ability to run the given task.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

Returns:

a TaskReservation for the task

Throws:

TaskRejectedException - if a reservation cannot be made

reserveTask

TaskReservation reserveTask(KernelRunnable task,
                            Identity owner,
                            long startTime)

Reserves the ability to run the given task at a specified point in the future. The startTime is a value in milliseconds measured from 1/1/1970.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

Returns:

a TaskReservation for the task

Throws:

TaskRejectedException - if a reservation cannot be made

scheduleTask

void scheduleTask(KernelRunnable task,
                  Identity owner)

Schedules a task to run as soon as possible based on the specific scheduler implementation.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

Throws:

TaskRejectedException - if the given task is not accepted

scheduleTask

void scheduleTask(KernelRunnable task,
                  Identity owner,
                  long startTime)

Schedules a task to run at a specified point in the future. The startTime is a value in milliseconds measured from 1/1/1970. If the starting time has already passed, then the task is run immediately.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

Throws:

TaskRejectedException - if the given task is not accepted

scheduleRecurringTask

RecurringTaskHandle scheduleRecurringTask(KernelRunnable task,
                                          Identity owner,
                                          long startTime,
                                          long period)

Schedules a task to start running at a specified point in the future, and continuing running on a regular period starting from that initial point. Unlike the other scheduleTask methods, this method will never fail to accept to the task so there is no need for a reservation. Note, however, that the task will not actually start executing until start is called on the returned RecurringTaskHandle.

At each execution point the scheduler will make a best effort to run the task, but based on available resources scheduling the task may fail. Regardless, the scheduler will always try again at the next execution time.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

period - the length of time in milliseconds between each recurring task execution

Returns:

a RecurringTaskHandle used to manage the recurring task

Throws:

IllegalArgumentException - if period is less than or equal to zero

createTaskQueue

TaskQueue createTaskQueue()

Creates a new TaskQueue to use in scheduling dependent tasks. Once a given task has completed the next task will be submitted to the scheduler to run.

Returns:

a new TaskQueue