com.sun.sgs.impl.kernel
Class TransactionSchedulerImpl

java.lang.Object
  com.sun.sgs.impl.kernel.TransactionSchedulerImpl

All Implemented Interfaces:

PriorityScheduler, TransactionScheduler, ProfileListener

final class TransactionSchedulerImpl
extends Object
implements TransactionScheduler, PriorityScheduler, ProfileListener

Package-private implementation of TransactionScheduler that is used by the system for scheduling and running all transactional tasks. This class supports the following configuration properties:

Property: "com.sun.sgs.impl.kernel.transaction.threads"
Default: "4"

The number of initial threads used to process transactional tasks.

Property: "com.sun.sgs.impl.kernel.scheduler.queue"
Default: "com.sun.sgs.impl.kernel.schedule.FIFOSchedulerQueue"

The implementation class used to track access to define which queue implementation should back this scheduler. The value of this property should be the name of a public, non-abstract class that implements the SchedulerQueue interface, and that provides a public constructor with the parameters Properties

Property: "com.sun.sgs.impl.kernel.scheduler.retry"
Default: "com.sun.sgs.impl.kernel.schedule.ImmediateRetryPolicy"

The implementation class used to define which retry policy implementation to use when tasks fail or abort. The value of this property should be the name of a public, non-abstract class that implements the SchedulerRetryPolicy interface, and that provides a public constructor with the parameters Properties

Field Summary

static String	CONSUMER_THREADS_PROPERTY The property used to define the default number of initial consumer threads.
static String	DEFAULT_CONSUMER_THREADS The default number of initial consumer threads.
static String	DEFAULT_SCHEDULER_QUEUE The default scheduler.
static String	DEFAULT_SCHEDULER_RETRY The default retry policy
static String	SCHEDULER_QUEUE_PROPERTY The property used to define which queue implementation should back this scheduler.
static String	SCHEDULER_RETRY_PROPERTY The property used to define which retry policy should be used in this scheduler

Fields inherited from interface com.sun.sgs.profile.ProfileListener

WINDOW_SIZE_PROPERTY

Constructor Summary

TransactionSchedulerImpl(Properties properties, TransactionCoordinator transactionCoordinator, ProfileCollectorHandle profileCollectorHandle, AccessCoordinatorHandle accessCoordinator)
Creates an instance of TransactionSchedulerImpl.

Method Summary

TaskQueue	createTaskQueue() Creates a new TaskQueue to use in scheduling dependent tasks.
void	propertyChange(PropertyChangeEvent event) Notifies this listener of a new change in the system properties.
void	report(ProfileReport profileReport) Reports a completed task that has been run through the scheduler.
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.
TaskReservation	reserveTask(KernelRunnable task, Identity owner, Priority priority) Reserves the ability to run the given task.
void	runTask(KernelRunnable task, Identity owner) Runs the given task synchronously, returning when the task has completed or throwing an exception if the task fails.
(package private) void	runUnboundedTask(KernelRunnable task, Identity owner) Package-private method that runs the given task in a transaction that is not bound by any timeout value (i.e., is bound only by the com.sun.sgs.txn.timeout.unbounded property value).
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.
void	scheduleTask(KernelRunnable task, Identity owner, Priority priority) Schedules a task to run as soon as possible based on the specific scheduler implementation.
(package private) void	setContext(KernelContext kernelContext) Package-private method used to set the context being used by the kernel.
void	shutdown() Tells this listener that the system is shutting down.

Methods inherited from class java.lang.Object

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

Field Detail

SCHEDULER_QUEUE_PROPERTY

public static final String SCHEDULER_QUEUE_PROPERTY

The property used to define which queue implementation should back this scheduler.

See Also:

Constant Field Values

DEFAULT_SCHEDULER_QUEUE

public static final String DEFAULT_SCHEDULER_QUEUE

The default scheduler.

See Also:

Constant Field Values

SCHEDULER_RETRY_PROPERTY

public static final String SCHEDULER_RETRY_PROPERTY

The property used to define which retry policy should be used in this scheduler

See Also:

Constant Field Values

DEFAULT_SCHEDULER_RETRY

public static final String DEFAULT_SCHEDULER_RETRY

The default retry policy

See Also:

Constant Field Values

CONSUMER_THREADS_PROPERTY

public static final String CONSUMER_THREADS_PROPERTY

The property used to define the default number of initial consumer threads.

See Also:

Constant Field Values

DEFAULT_CONSUMER_THREADS

public static final String DEFAULT_CONSUMER_THREADS

The default number of initial consumer threads.

See Also:

Constant Field Values

Constructor Detail

TransactionSchedulerImpl

TransactionSchedulerImpl(Properties properties,
                         TransactionCoordinator transactionCoordinator,
                         ProfileCollectorHandle profileCollectorHandle,
                         AccessCoordinatorHandle accessCoordinator)
                   throws Exception

Creates an instance of TransactionSchedulerImpl.

Parameters:

properties - the Properties for the system

transactionCoordinator - the TransactionCoordinator used by the system to manage transactions

profileCollectorHandle - the ProfileCollectorHandler used to manage collection of per-task profiling data

accessCoordinator - the AccessCoordinator used by the system to managed shared data

Throws:

InvocationTargetException - if there is a failure initializing the SchedulerQueue

Exception - if there is any failure creating the scheduler

Method Detail

setContext

void setContext(KernelContext kernelContext)

Package-private method used to set the context being used by the kernel.

Parameters:

kernelContext - the KernelContext for this scheduler

reserveTask

public TaskReservation reserveTask(KernelRunnable task,
                                   Identity owner)

Reserves the ability to run the given task.

Specified by:

reserveTask in interface TransactionScheduler

Parameters:

task - the KernelRunnable to execute

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

Returns:

a TaskReservation for the task

reserveTask

public 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.

Specified by:

reserveTask in interface TransactionScheduler

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

scheduleTask

public void scheduleTask(KernelRunnable task,
                         Identity owner)

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

Specified by:

scheduleTask in interface TransactionScheduler

Parameters:

task - the KernelRunnable to execute

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

scheduleTask

public 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.

Specified by:

scheduleTask in interface TransactionScheduler

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

scheduleRecurringTask

public 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.

Specified by:

scheduleRecurringTask in interface TransactionScheduler

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

createTaskQueue

public TaskQueue createTaskQueue()

Creates a new TaskQueue to use in scheduling dependent tasks. Each task added to the queue will be run in a separate transaction. Re-try is applied to each transaction, and the next task in the queue is run only after the current task either completes successfully or fails permanently.

Specified by:

createTaskQueue in interface TransactionScheduler

Returns:

a new TaskQueue

runTask

public void runTask(KernelRunnable task,
                    Identity owner)
             throws Exception

Runs the given task synchronously, returning when the task has completed or throwing an exception if the task fails. It is up to the TransactionScheduler implementation to decide when to run this task, so the task may be run immediately or it might be queued behind waiting tasks. The task may be handed off to another thread of control for execution. In all cases, the caller will block until the task completes or fails permanently.

As with all methods of TransactionScheduler, tasks run with runTask will be run transactionally. If the caller is not in an active transaction, then a transaction is created to run the task. If the caller is already part of an active transaction, then the task is run as part of that transaction, and the owner paramater is ignored.

When the caller is not part of an active transaction, then when the given task completes it will also attempt to commit. If committing the transaction fails, normal re-try behavior is applied. If the task requests to be re-tried, then it will be re-run according to the scheduler implementation's policy. In this case, runTask will not return until the task finally succeeds, or is no longer re-tried.

In the event that the caller is part of an active transaction, then there is no re-try applied in the case of a failure, and the transaction is not committed if the task completes successfully. This is because the system does not support nested transactions, and so the decision to commit or re-try is left to the active transaction.

Specified by:

runTask in interface TransactionScheduler

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

InterruptedException - if the calling thread is interrupted and the associated task does not complete

Exception - if the task fails and is not re-tried

reserveTask

public TaskReservation reserveTask(KernelRunnable task,
                                   Identity owner,
                                   Priority priority)

Reserves the ability to run the given task. The scheduler will make a best effort to honor the requested priority.

Specified by:

reserveTask in interface PriorityScheduler

Parameters:

task - the KernelRunnable to execute

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

priority - the requested Priority

Returns:

a TaskReservation for the task

scheduleTask

public void scheduleTask(KernelRunnable task,
                         Identity owner,
                         Priority priority)

Schedules a task to run as soon as possible based on the specific scheduler implementation. The scheduler will make a best effort to honor the requested priority.

Specified by:

scheduleTask in interface PriorityScheduler

Parameters:

task - the KernelRunnable to execute

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

priority - the requested Priority

propertyChange

public void propertyChange(PropertyChangeEvent event)

Notifies this listener of a new change in the system properties. This method is called for any property that changes.

The current list of supported property names is as follows:

name	description	new value	old value
com.sun.sgs.profile.newop	a new operation is registered with the system.	the new operation : ProfileOperation	null
com.sun.sgs.profile.threadcount	the number of threads in the system has changed.	the current number of threads : Integer	the previous number of threads : Integer
com.sun.sgs.profile.nodeid	the local node has been assigned a unique identifier	the identifier for the local node: Long	null

Specified by:

propertyChange in interface ProfileListener

Parameters:

event - A PropertyChangeEvent object describing the name of the property, its old and new values and the source of the change.

report

public void report(ProfileReport profileReport)

Reports a completed task that has been run through the scheduler. The task may have completed successfully or may have failed. If a task is re-tried, then this method will be called multiple times for each re-try of the same task. Note that in this case the scheduledStartTime will remain constant but the actualStartTime will change for each re-try of the same task.

Specified by:

report in interface ProfileListener

Parameters:

profileReport - the ProfileReport for the task

shutdown

public void shutdown()

Tells this listener that the system is shutting down.

Specified by:

shutdown in interface ProfileListener

runUnboundedTask

void runUnboundedTask(KernelRunnable task,
                      Identity owner)
                throws Exception

Package-private method that runs the given task in a transaction that is not bound by any timeout value (i.e., is bound only by the com.sun.sgs.txn.timeout.unbounded property value).

Parameters:

task - the KernelRunnable to run transactionally

owner - the Identity that owns the task

Throws:

IllegalStateException - if this method is called from an actively running transaction

Exception - if there is any failure that does not result in re-trying the task