com.sun.sgs.kernel.schedule
Interface SchedulerQueue

All Known Implementing Classes:

FIFOSchedulerQueue, WindowSchedulerQueue

public interface SchedulerQueue

This interface is used to define the backing queue for a scheduler. Essentially, implementations are used to define some policy for ordering task execution.

All implementations must implement a constructor of the form (java.util.Properties).

Method Summary

void	addTask(ScheduledTask task) Adds a task to the scheduler.
RecurringTaskHandle	createRecurringTaskHandle(ScheduledTask task) Creates a RecurringTaskHandle for the associated task.
ScheduledTask	getNextTask(boolean wait) Returns the next task to run, blocking if wait is true.
int	getNextTasks(Collection<? super ScheduledTask> tasks, int max) Places at most the next max tasks available into the provided Collection.
int	getReadyCount() Returns the number of tasks that are ready to run.
void	notifyCancelled(ScheduledTask task) Notifies the scheduler that the given task has been cancelled.
TaskReservation	reserveTask(ScheduledTask task) Reserves a space for a task.
void	shutdown() Tells this SchedulerQueue to shutdown.

Method Detail

getReadyCount

int getReadyCount()

Returns the number of tasks that are ready to run. This does not include any pending or recurring tasks that have not yet come time to run.

Returns:

the number of tasks ready to run

getNextTask

ScheduledTask getNextTask(boolean wait)
                          throws InterruptedException

Returns the next task to run, blocking if wait is true. If not waiting, it returns null if nothing is available.

Parameters:

wait - whether to wait for a task to become available

Returns:

the next ScheduledTask or null

Throws:

InterruptedException - if the thread is interrupted while waiting for a task

getNextTasks

int getNextTasks(Collection<? super ScheduledTask> tasks,
                 int max)

Places at most the next max tasks available into the provided Collection. This method does not block, so it may not provide any tasks. The number of tasks provided is returned.

Note that there is no guarentee that the tasks provided are all contiguous. That is, if two calls are made at the same time to this method, or a call to getNextTask is made at the same time, the scheduler does not have to provide the next max tasks to one consumer before servicing others. If this behavior is needed, the caller needs to synchronize access. The tasks are guaranteed to be in correct order if the provided Collection is ordered.

Parameters:

tasks - the Collection into which the tasks are put

max - the maximum number of tasks to get

Returns:

the number of tasks provided

reserveTask

TaskReservation reserveTask(ScheduledTask task)

Reserves a space for a task.

Parameters:

task - the ScheduledTask to reserve

Returns:

a TaskReservation for the task

Throws:

TaskRejectedException - if a reservation cannot be made, or if the task is recurring

addTask

void addTask(ScheduledTask task)

Adds a task to the scheduler. This task is executed only once, but may be executed immediately or in the future.

Note that if this is a recurring task, then a call to its getRecurringTaskHandle method must return a handle provided by a call to this implementation's createRecurringTaskHandle method. Note also that it is up to the caller to re-schedule this task for each recurrence, and that each such call must provide a unique instance of ScheduledTask.

Parameters:

task - the ScheduledTask to add

Throws:

TaskRejectedException - if the task cannot be added

createRecurringTaskHandle

RecurringTaskHandle createRecurringTaskHandle(ScheduledTask task)

Creates a RecurringTaskHandle for the associated task. The associated task will not actually be available through this queue until start is called on the returned handle. The ScheduledTask instance must never have been previously used to schedule a recurring task. Note that after the initial execution of this task, it is up to the caller to schedule each recurrence through a call to addTask.

Parameters:

task - the ScheduledTask to run recurringly

Returns:

a RecurringTaskHandle that manages the task

Throws:

IllegalArgumentException - if the task has already been scheduled as a recurring task

notifyCancelled

void notifyCancelled(ScheduledTask task)

Notifies the scheduler that the given task has been cancelled. An implementation does not need to do anything in reaction to this call as long as the given task will not run. If this task is unknown, or has already run, this call may be ignored.

Parameters:

task - the ScheduledTask that has been cancelled

shutdown

void shutdown()

Tells this SchedulerQueue to shutdown.