org.jgroups.util
Class TimeScheduler

java.lang.Object
  extended by java.util.concurrent.AbstractExecutorService
      extended by java.util.concurrent.ThreadPoolExecutor
          extended by java.util.concurrent.ScheduledThreadPoolExecutor
              extended by org.jgroups.util.TimeScheduler
All Implemented Interfaces:
java.util.concurrent.Executor, java.util.concurrent.ExecutorService, java.util.concurrent.ScheduledExecutorService, ThreadManager

public class TimeScheduler
extends java.util.concurrent.ScheduledThreadPoolExecutor
implements ThreadManager

Fixed-delay & fixed-rate single thread scheduler

The scheduler supports varying scheduling intervals by asking the task every time for its next preferred scheduling interval. Scheduling can either be fixed-delay or fixed-rate. The notions are borrowed from java.util.Timer and retain the same meaning. I.e. in fixed-delay scheduling, the task's new schedule is calculated as:
new_schedule = time_task_starts + scheduling_interval

In fixed-rate scheduling, the next schedule is calculated as:
new_schedule = time_task_was_supposed_to_start + scheduling_interval

The scheduler internally holds a queue of tasks sorted in ascending order according to their next execution time. A task is removed from the queue if it is cancelled, i.e. if TimeScheduler.Task.isCancelled() returns true.

The scheduler internally uses a java.util.SortedSet to keep tasks sorted. java.util.Timer uses an array arranged as a binary heap that doesn't shrink. It is likely that the latter arrangement is faster.

Initially, the scheduler is in SUSPENDed mode, start() need not be called: if a task is added, the scheduler gets started automatically. Calling start() starts the scheduler if it's suspended or stopped else has no effect. Once stop() is called, added tasks will not restart it: start() has to be called to restart the scheduler.

Version:
$Id: TimeScheduler.java,v 1.23.4.4 2008/06/19 15:36:28 vlada Exp $
Author:
Bela Ban

Nested Class Summary
static interface TimeScheduler.Task
          The interface that submitted tasks must implement
 
Nested classes/interfaces inherited from class java.util.concurrent.ThreadPoolExecutor
java.util.concurrent.ThreadPoolExecutor.AbortPolicy, java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy, java.util.concurrent.ThreadPoolExecutor.DiscardOldestPolicy, java.util.concurrent.ThreadPoolExecutor.DiscardPolicy
 
Field Summary
protected static org.apache.commons.logging.Log log
           
 
Constructor Summary
TimeScheduler()
          Create a scheduler that executes tasks in dynamically adjustable intervals
TimeScheduler(int corePoolSize)
           
TimeScheduler(ThreadFactory factory)
           
TimeScheduler(ThreadFactory factory, int max_threads)
           
 
Method Summary
protected  void afterExecute(java.lang.Runnable r, java.lang.Throwable t)
           
 java.lang.String dumpTaskQueue()
           
 ThreadDecorator getThreadDecorator()
          Gets the ThreadDecorator associated with this manager.
 java.util.concurrent.ScheduledFuture<?> scheduleWithDynamicInterval(TimeScheduler.Task t)
          Add a task for execution at adjustable intervals
 java.util.concurrent.ScheduledFuture<?> scheduleWithDynamicInterval(TimeScheduler.Task task, boolean relative)
          Schedule a task for execution at varying intervals.
 void setThreadDecorator(ThreadDecorator threadDecorator)
          Sets the ThreadDecorator associated this manager should use.
 int size()
          Answers the number of tasks currently in the queue.
 void start()
          Start the scheduler, if it's suspended or stopped
 void stop()
          Stop the scheduler if it's running.
 
Methods inherited from class java.util.concurrent.ScheduledThreadPoolExecutor
decorateTask, decorateTask, execute, getContinueExistingPeriodicTasksAfterShutdownPolicy, getExecuteExistingDelayedTasksAfterShutdownPolicy, getQueue, remove, schedule, schedule, scheduleAtFixedRate, scheduleWithFixedDelay, setContinueExistingPeriodicTasksAfterShutdownPolicy, setExecuteExistingDelayedTasksAfterShutdownPolicy, shutdown, shutdownNow, submit, submit, submit
 
Methods inherited from class java.util.concurrent.ThreadPoolExecutor
allowCoreThreadTimeOut, allowsCoreThreadTimeOut, awaitTermination, beforeExecute, finalize, getActiveCount, getCompletedTaskCount, getCorePoolSize, getKeepAliveTime, getLargestPoolSize, getMaximumPoolSize, getPoolSize, getRejectedExecutionHandler, getTaskCount, getThreadFactory, isShutdown, isTerminated, isTerminating, prestartAllCoreThreads, prestartCoreThread, purge, setCorePoolSize, setKeepAliveTime, setMaximumPoolSize, setRejectedExecutionHandler, setThreadFactory, terminated
 
Methods inherited from class java.util.concurrent.AbstractExecutorService
invokeAll, invokeAll, invokeAny, invokeAny, newTaskFor, newTaskFor
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.concurrent.ExecutorService
awaitTermination, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated
 

Field Detail

log

protected static final org.apache.commons.logging.Log log
Constructor Detail

TimeScheduler

public TimeScheduler()
Create a scheduler that executes tasks in dynamically adjustable intervals


TimeScheduler

public TimeScheduler(ThreadFactory factory)

TimeScheduler

public TimeScheduler(ThreadFactory factory,
                     int max_threads)

TimeScheduler

public TimeScheduler(int corePoolSize)
Method Detail

getThreadDecorator

public ThreadDecorator getThreadDecorator()
Description copied from interface: ThreadManager
Gets the ThreadDecorator associated with this manager.

Specified by:
getThreadDecorator in interface ThreadManager
Returns:
the ThreadDecorator, or null if there is none.

setThreadDecorator

public void setThreadDecorator(ThreadDecorator threadDecorator)
Description copied from interface: ThreadManager
Sets the ThreadDecorator associated this manager should use.

Specified by:
setThreadDecorator in interface ThreadManager
Parameters:
threadDecorator - the ThreadDecorator, or null.

dumpTaskQueue

public java.lang.String dumpTaskQueue()

scheduleWithDynamicInterval

public java.util.concurrent.ScheduledFuture<?> scheduleWithDynamicInterval(TimeScheduler.Task task,
                                                                           boolean relative)
Schedule a task for execution at varying intervals. After execution, the task will get rescheduled after TimeScheduler.Task.nextInterval() milliseconds. The task is neve done until nextInterval() return a value <= 0 or the task is cancelled.

Parameters:
task - the task to execute
relative - scheduling scheme: true:
Task is rescheduled relative to the last time it actually started execution

false:
Task is scheduled relative to its last execution schedule. This has the effect that the time between two consecutive executions of the task remains the same.

Note that relative is always true; we always schedule the next execution relative to the last *actual* (not scheduled) execution


scheduleWithDynamicInterval

public java.util.concurrent.ScheduledFuture<?> scheduleWithDynamicInterval(TimeScheduler.Task t)
Add a task for execution at adjustable intervals

Parameters:
t - the task to execute

size

public int size()
Answers the number of tasks currently in the queue.

Returns:
The number of tasks currently in the queue.

start

public void start()
Start the scheduler, if it's suspended or stopped


stop

public void stop()
          throws java.lang.InterruptedException
Stop the scheduler if it's running. Switch to stopped, if it's suspended. Clear the task queue, cancelling all un-executed tasks

Throws:
java.lang.InterruptedException - if interrupted while waiting for thread to return

afterExecute

protected void afterExecute(java.lang.Runnable r,
                            java.lang.Throwable t)
Overrides:
afterExecute in class java.util.concurrent.ThreadPoolExecutor


Copyright ? 1998-2008 Bela Ban. All Rights Reserved.