simple.util.schedule
Class Scheduler

java.lang.Object
  extended by simple.util.schedule.Scheduler
Direct Known Subclasses:
PulseScheduler

public class Scheduler
extends java.lang.Object

The Scheduler is used for scheduling arbitrary objects. When arbitrary objects are enqueued into a Scheduler the Scheduler object will guarantee that that object will not be dequeued until its timeout has expired.

This guarantees that an object is returned when the dequeue method is invoked. If there are no objects within the Scheduler then the thread that invoked this dequeue method will wait until there is an object to dequeue. If however there is an object within the Scheduler the dequeue method will block the thread until such time as the objects timeout has expired or if another object has been enqueued concurrently that will allow the dequeue method to return earlier then it returns the object which has the least time to wait.

The waiting of an object is based on the time when it is allowed to be released. For instance if an object with a given timeout of 1000 ms is enqueued then the time when that object is permitted to be released is the sum of the System.currentTimeMillis and the timeout which is 1000, relative to the currentTime, that is from the time that it is scheduled.

This ensures regardless of the timeout peroid an object will always be released at some time because its priority is based on the time it entered the SchedulerQueue.

Author:
Niall Gallagher

Nested Class Summary
 class Scheduler.Entry
          This is used to keep objects with there time of release.
 
Field Summary
protected static long DEFAULT_MAX
          The maximum length of time an object can be enqueued.
protected  long max
          The default maximum time a object can wait.
protected  simple.util.schedule.SchedulerQueue queue
          This is the PriorityQueue for the objects.
protected  simple.util.schedule.Registry registry
          List of current dequeuers for this Scheduler.
 
Constructor Summary
Scheduler()
          This will create a default Scheduler.
Scheduler(long max)
          This creates a Scheduler object with the maximum timeout specified.
 
Method Summary
protected  long currentTime()
          This returns the currentTime in milliseconds from the creation of this.
 java.lang.Object dequeue()
          This is used to dequeue the objects from the Scheduler.
 void enqueue(java.lang.Object object, long wait)
          This schedules objects so that they will not be released until the specified timeout has expired.
protected  void enqueue(Scheduler.Entry entry)
          This adds an entry object into the SchedulerQueue this will set a priority based on the time this object is to be released at, that is the sooner that the entry is to be released the higher its priority.
protected  void interrupt(Scheduler.Entry entry)
          This method is important for enqueuing items as it tells the Registry what the timeout of an incomming item is.
protected  void register(long awaken)
          This will register with the Registry object.
protected  void sleep(long awaken)
          This will put the curent thread to sleep.
protected  void unregister()
          This will unregister the current thread from the Registry object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX

protected static final long DEFAULT_MAX
The maximum length of time an object can be enqueued.

See Also:
Constant Field Values

queue

protected simple.util.schedule.SchedulerQueue queue
This is the PriorityQueue for the objects.


registry

protected simple.util.schedule.Registry registry
List of current dequeuers for this Scheduler.


max

protected long max
The default maximum time a object can wait.

Constructor Detail

Scheduler

public Scheduler()
This will create a default Scheduler. The default Scheduler will allow timeouts of up to 60000 miliseconds. This means that an object that has been scheduled for release at a specified time will be guaranteed to be released at least 1 minute after it was scheduled and if the timeout is less than 1 minute then it will be released after that timeout has expired.


Scheduler

public Scheduler(long max)
This creates a Scheduler object with the maximum timeout specified. This will ensure that no object will be blocked for longer than the specified timeout. If an object is enqueued with a timeout greater than the specified timeout then the timeout is capped to the max.

Parameters:
max - the maximum timeout for this Scheduler
Method Detail

enqueue

public void enqueue(java.lang.Object object,
                    long wait)
This schedules objects so that they will not be released until the specified timeout has expired. If this timeout is greater than the maximum timeout then it is capped and released once the maximum timeout has expired instead.

Parameters:
object - the object to be scheduled for a timeout
wait - time it is to wait within the Scheduler

interrupt

protected void interrupt(Scheduler.Entry entry)
This method is important for enqueuing items as it tells the Registry what the timeout of an incomming item is. If the item has a timeout that is less than a dequeuer then the thread that is dequeuing the item with the larger timeout is interrupted.

Parameters:
entry - this is the new entry that has been enqueued

enqueue

protected void enqueue(Scheduler.Entry entry)
This adds an entry object into the SchedulerQueue this will set a priority based on the time this object is to be released at, that is the sooner that the entry is to be released the higher its priority. The actual priority is the time of release times -1.

Parameters:
entry - the entry object that is being queued

dequeue

public java.lang.Object dequeue()
                         throws java.lang.InterruptedException
This is used to dequeue the objects from the Scheduler. This will return an object only when it has one whose timeout has expired. If there are no objects in the Scheduler then it will block the thread until one becomes available. This is guaranteed to return an object once an objects timeout has expired. If a thread is blocked trying to retrive an object whose timeout has not yet expired and another object is entered concurrently which does not have to wait such a long time then the thread will become unblocked and return the object with the least timeout. This method cannot be synchronized because the thread will wait when the SchedulerQueue isEmpty and thus that thread will cause a deadlock situation, because it will have the lock.

Returns:
the returns the next object which timeout has expired
Throws:
java.lang.InterruptedException - thrown if the thread is interrupted

unregister

protected void unregister()
This will unregister the current thread from the Registry object. This means that this thread will no longer recive interrupts from the Registry.


register

protected void register(long awaken)
This will register with the Registry object. This basically means that this thread wishes to recieve interrupts if there is a thread that calls the interrupt method of the Registry with an wake timeout less that this threads wake timeout.

Parameters:
awaken - the time this thread will stop sleeping

sleep

protected void sleep(long awaken)
              throws java.lang.InterruptedException
This will put the curent thread to sleep. This thread may be woken by the Registry if there is a Registry.interrupt method invoked that has a sleep time less than the registered thread.

Parameters:
awaken - the time that this thread will stop sleeping
Throws:
java.lang.InterruptedException - Thread.sleep throws this

currentTime

protected long currentTime()
This returns the currentTime in milliseconds from the creation of this. The time is made smaller by subtracting the time this object was created at. This time will return an increasing time from 0 to the Long.MAX_VALUE.

Returns:
the currentTime minus the time that this was created.