com.sun.jini.thread
Class WakeupManager

java.lang.Object
  extended by com.sun.jini.thread.WakeupManager

public class WakeupManager
extends Object

A Queue of timed tasks. Each task implements Runnable. Events can either be executed in the queue's thread or in their own thread.

A task is an object that implements Runnable. It is scheduled by invoking schedule with a time at which it should be run. When that time arrives (approximately) the task will be pulled off the queue and have its run method invoked.

A schedule request can specify a WakeupManager.ThreadDesc, which will define the parameters of a thread to be created to run the Runnable. You can specify the group, whether the thread is a daemon thread, and the priority. Additionally you can use a subclass of WakeupManager.ThreadDesc and override the thread method to further customize thread creation.

When a task is scheduled, a WakeupManager.Ticket is returned that can be used to cancel the event if desired.

The queue requires its own thread, whose parameters can be defined via a ThreadDesc if desired. The queue's thread will be started when the first task is scheduled. If the queue becomes empty the thread will be terminated after a configurable delay. The thread will be re-started if a new task is scheduled.

While it is theoretically possible to obtain the queue's thread and interrupt it, the results of doing so are undefined. If a client wishes to stop the queue's thread the client should either remove all the tasks or call stop(). Note, calling stop will cause future schedule calls to fail with an IllegalStateException.

WakeupManager supports the queueThreadTimeout configuration entry, with the component com.sun.jini.thread.WakeupManager.

queueThreadTimeout
  Type: long
  Default: 30,000 milliseconds
  Description: How long, in milliseconds, the queue's thread will be left running if there are no scheduled tasks. Must be a non-negative long value. This configuration entry is consulted when the WakeupManager is initially created.

This class uses the Logger named com.sun.jini.thread.WakeupManager to log information at the following logging levels:

Level Description
SEVERE exceptions thrown when we attempt to create the queue's thread
WARNING exceptions thrown by the run methods of tasks, by the ThreadDesc's of tasks, or if the queue's thread is interrupted
FINEST how many milliseconds until the next event and when the queue's thread is stopped or started

Author:
Sun Microsystems, Inc.
See Also:
Runnable

Nested Class Summary
private  class WakeupManager.Kicker
          The kicker work.
static class WakeupManager.ThreadDesc
          Description of a future thread.
static class WakeupManager.Ticket
          A ticket that can be used for cancelling a future task.
 
Field Summary
private static String COMPONENT_NAME
          Component we pull configuration entries from and our logger name
private  SortedSet contents
          The queue.
private static DateFormat dateFmt
          DataFormat used by WakeupManager.Ticket to format its toString return value.
private  boolean dead
          true if we have been stopped.
private static long DEFAULT_QUEUE_THREAD_TIMEOUT
          Default value for queueThreadTimeout
private  WakeupManager.Ticket head
          First item in contents
private  WakeupManager.Kicker kicker
          The Runnable for the queue's thread
private  WakeupManager.ThreadDesc kickerDesc
          ThreadDesc we use to create kicker threads
private  Thread kickerThread
          The queue's thread
private static Logger logger
          Logger for this class and nested classes
private  long nextBreaker
          Next tie breaker ticket
private  long queueThreadTimeout
          If there are no registered tasks number of milliseconds to wait before killing the kicker thread
 
Constructor Summary
WakeupManager()
          Create a new WakeupManager.
WakeupManager(WakeupManager.ThreadDesc desc)
          Create a new WakeupManager.
WakeupManager(WakeupManager.ThreadDesc desc, Configuration config)
          Create a new WakeupManager.
 
Method Summary
 void cancel(WakeupManager.Ticket t)
          Cancel the given ticket.
 void cancelAll()
          Cancel all tickets.
private  void checkHead()
          Called whenever we change contents to update head and see if we need to wake up the queue thread.
 boolean isEmpty()
          Return whether the queue is currently empty.
protected  WakeupManager.Ticket newTicket(long when, Runnable task, WakeupManager.ThreadDesc threadDesc)
          Create a new ticket with the specified values for when the task should be run, what task should be run, and what sort of thread the task should be run in.
 WakeupManager.Ticket schedule(long when, Runnable task)
          Schedule the given task for the given time.
 WakeupManager.Ticket schedule(long when, Runnable task, WakeupManager.ThreadDesc threadDesc)
          Schedule the given task for the given time, to be run in a thread.
 void stop()
          Stop executing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COMPONENT_NAME

private static final String COMPONENT_NAME
Component we pull configuration entries from and our logger name

See Also:
Constant Field Values

DEFAULT_QUEUE_THREAD_TIMEOUT

private static final long DEFAULT_QUEUE_THREAD_TIMEOUT
Default value for queueThreadTimeout

See Also:
Constant Field Values

queueThreadTimeout

private final long queueThreadTimeout
If there are no registered tasks number of milliseconds to wait before killing the kicker thread


contents

private final SortedSet contents
The queue. Also the object we use for locking, multi-threaded access to all the other fields is arbitrated by synchronizing on this object.


kickerDesc

private final WakeupManager.ThreadDesc kickerDesc
ThreadDesc we use to create kicker threads


kicker

private final WakeupManager.Kicker kicker
The Runnable for the queue's thread


nextBreaker

private long nextBreaker
Next tie breaker ticket


head

private WakeupManager.Ticket head
First item in contents


kickerThread

private Thread kickerThread
The queue's thread


dead

private boolean dead
true if we have been stopped.


dateFmt

private static DateFormat dateFmt
DataFormat used by WakeupManager.Ticket to format its toString return value.


logger

private static final Logger logger
Logger for this class and nested classes

Constructor Detail

WakeupManager

public WakeupManager()
Create a new WakeupManager. Equivalent to.
     WakeupManager(new ThreadDesc())
 

See Also:
WakeupManager.ThreadDesc

WakeupManager

public WakeupManager(WakeupManager.ThreadDesc desc)
Create a new WakeupManager. The thread used for timing will be created according to the provided ThreadDesc.

Throws:
NullPointerException - if desc is null

WakeupManager

public WakeupManager(WakeupManager.ThreadDesc desc,
                     Configuration config)
              throws ConfigurationException
Create a new WakeupManager. The thread used for timing will be created according to the provided ThreadDesc. Optionally pass a configuration to control various implementation specific behaviors.

Throws:
ConfigurationException - if if an exception occurs while retrieving an item from the given Configuration object
NullPointerException - if either argument is null
Method Detail

newTicket

protected WakeupManager.Ticket newTicket(long when,
                                         Runnable task,
                                         WakeupManager.ThreadDesc threadDesc)
Create a new ticket with the specified values for when the task should be run, what task should be run, and what sort of thread the task should be run in.

Parameters:
when - when the task should run, an absolute time
task - what task should be run
threadDesc - if non-null the object to use to create the thread the task should be run in, if null the task should be run in the manager's thread.
Throws:
NullPointerException - if task is null

schedule

public WakeupManager.Ticket schedule(long when,
                                     Runnable task)
Schedule the given task for the given time. The task's run method will be executed synchronously in the queue's own thread, so it should be brief or it will affect whether future events will be executed at an appropriate time.

Throws:
NullPointerException - if task is null
IllegalStateException - if the manager has been stopped

schedule

public WakeupManager.Ticket schedule(long when,
                                     Runnable task,
                                     WakeupManager.ThreadDesc threadDesc)
Schedule the given task for the given time, to be run in a thread. When the time comes, a new thread will be created according to the ThreadDesc object provided. If threadDesc is null, this is equivalent to the other form of schedule.

Throws:
NullPointerException - if task is null
IllegalStateException - if the manager has been stopped

cancel

public void cancel(WakeupManager.Ticket t)
Cancel the given ticket.


cancelAll

public void cancelAll()
Cancel all tickets.


checkHead

private void checkHead()
Called whenever we change contents to update head and see if we need to wake up the queue thread. Assumes the caller holds the lock on contents.


isEmpty

public boolean isEmpty()
Return whether the queue is currently empty.


stop

public void stop()
Stop executing.



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.