one.world.core
Interface Animator

All Known Implementing Classes:
EventLoop, ThreadPool

public interface Animator

The definition of an animator. An animator executes code in a concurrency domain by providing the necessary thread(s) to apply event handlers on events. Since at any point in time there may be more event handler applications ready for processing than threads available in a concurrency domain, an animator maintains an internal queue of pending event handler applications.

Animators may be concurrent, that is, use one or more threads at any given time, or not, that is, always use only one thread. Furthermore, animators may be able to maintain a variable number of threads, limited by a low and a high watermark. An animator with a variable number of threads may automatically terminate a thread if that thread is idle for some predefined time. New threads are added to such an animator by a Animator.Controller.

Version:
$Revision: 1.11 $

Inner Class Summary
static class Animator.Controller
          Implementation of a controller.
 
Field Summary
static int ACTIVE
          The status code for an active animator.
static int DRAINED
          The status code for a drained animator.
static int INACTIVE
          The status code for an inactive animator.
static int TERMINATED
          The status code for a terminated animator.
 
Method Summary
 int addThreads(int number)
          Add up to the specified number of threads to this animator.
 boolean enqueue(EventHandler handler, Event event)
          Enqueue the specified event handler application.
 boolean enqueueFirst(EventHandler handler, Event event)
          Enqueue the specified event handler application in front of the queue.
 void enqueueForced(EventHandler handler, Event event)
          Forcibly enqueue the specified event handler application in front of the queue.
 int getMaxThreadNumber()
          Get the maximum number of threads for this animator.
 int getMinThreadNumber()
          Get the minimum number of threads for this animator.
 List getQueue()
          Get a list of event handler applications for this animator's queue.
 int getQueueCapacity()
          Get the capacity of this animator's queue or -1 if the capacity is unlimited.
 int getQueueSize()
          Get the current size of this animator's queue.
 int getStatus()
          Get the current status for this animator.
 int getThreadNumber()
          Get the current number of threads for this animator.
 boolean isConcurrent()
          Determine whether this animator is concurrent, that is, whether it uses more than one thread.
 boolean isQueueEmpty()
          Determine whether this animator's queue is empty.
 void setMaxThreadNumber(int number)
          Set the maximum number of threads for this animator.
 void setMinThreadNumber(int number)
          Set the minimum number of threads for this animator.
 void setStatus(int status)
          Set the status for this animator to the specified status.
 

Field Detail

ACTIVE

public static final int ACTIVE
The status code for an active animator.

INACTIVE

public static final int INACTIVE
The status code for an inactive animator.

DRAINED

public static final int DRAINED
The status code for a drained animator.

TERMINATED

public static final int TERMINATED
The status code for a terminated animator.
Method Detail

isConcurrent

public boolean isConcurrent()
Determine whether this animator is concurrent, that is, whether it uses more than one thread.
Returns:
true if this animator is concurrent.

getMinThreadNumber

public int getMinThreadNumber()
Get the minimum number of threads for this animator.
Returns:
The minimum number of threads for this animator.
Throws:
IllegalStateException - Signals that this animator has terminated.

getThreadNumber

public int getThreadNumber()
Get the current number of threads for this animator.
Returns:
The number of threads for this animator.
Throws:
IllegalStateException - Signals that this animator has terminated.

getMaxThreadNumber

public int getMaxThreadNumber()
Get the maximum number of threads for this animator.
Returns:
The maximum numberf of threads for this animator.
Throws:
IllegalStateException - Signals that this animator has terminated.

setMinThreadNumber

public void setMinThreadNumber(int number)
Set the minimum number of threads for this animator. If the new minimum number of threads is larger than the current maximum number of threads, the maximum number is also set to the specified number of threads.
Parameters:
number - The new miminum number of threads for this animator.
Throws:
IllegalArgumentException - Signals that number is not positive.
IllegalStateException - Signals that this animator has terminated.
UnsupportedOperationException - Signals that the number of threads for this animator is constant and cannot be changed.

addThreads

public int addThreads(int number)
Add up to the specified number of threads to this animator. This method adds zero or more threads to this animator and returns that number. The actual number of threads added is the minimum of the specified number and of the difference between the maximum number of threads and the current number of threads for this animator.
Parameters:
number - The number of threads to add to this animator.
Returns:
The number of threads actually added to this animator.
Throws:
IllegalArgumentException - Signals that number is not positive.
IllegalStateException - Signals that this animator has terminated.
UnsupportedOperationException - Signals that the number of threads for this animator is constant and cannot be changed.

setMaxThreadNumber

public void setMaxThreadNumber(int number)
Set the maximum number of threads for this animator. If the new maximum number of threads is smaller than the current minimum number of threads, the minimum number is also set to the specified number of threads.
Parameters:
number - The new maxmimum number of threads for this animator.
Throws:
IllegalArgumentException - Signals that number is not positive.
IllegalStateException - Signals that this animator has terminated.
UnsupportedOperationException - Signals that the number of threads for this animator is constant and cannot be changed.

getStatus

public int getStatus()
Get the current status for this animator.
Returns:
The current status for this animator.
See Also:
setStatus(int)

setStatus

public void setStatus(int status)
Set the status for this animator to the specified status. This method changes the status of this animator if the specified status is different from its current status. It returns only after the status change is complete.

An active animator uses its thread(s) to process pending event handler applications. An inactive animator still enqueues new event handler applications, but all its threads are idle and not executing pending event handler applications. A drained animator does not enqueue new event handler applications and all its threads are idle. Though, they only become idle after having processed all pending event handler applications. A terminated animator has released its thread(s) and does not accept new event handler applications.

Valid state transitions are as follows: From the active state to either the inactive or the drained state. From the inactive or the drained state to any of the four states. An animator cannot leave the terminated state, once it is in that state.

Parameters:
status - The new status for this animator.
Throws:
IllegalArgumentException - Signals that status is not a valid status code or that the requested status results in an invalid state transition.
IllegalStateException - Signals that this animator has terminated.

enqueue

public boolean enqueue(EventHandler handler,
                       Event event)
Enqueue the specified event handler application.
Parameters:
handler - The handler to apply.
event - The event to apply the handler on.
Returns:
true if the event handler application has been successfully enqueued.
Throws:
IllegalStateException - Signals that this animator has terminated.

enqueueFirst

public boolean enqueueFirst(EventHandler handler,
                            Event event)
Enqueue the specified event handler application in front of the queue.
Parameters:
handler - The handler to apply.
event - The event to apply the handler on.
Returns:
true if the event handler application has been successfully enqueued.
Throws:
IllegalStateException - Signals that this animator has terminated.

enqueueForced

public void enqueueForced(EventHandler handler,
                          Event event)
Forcibly enqueue the specified event handler application in front of the queue. If this animator's queue is full, the specified event handler application replaces the event handler application at the head of the queue. Furthermore, if this animator is drained, the specified event handler application is still enqueued.
Parameters:
handler - The handler to apply.
event - The event to apply the handler on.
Throws:
IllegalStateException - Signals that this animator has terminated.

getQueueCapacity

public int getQueueCapacity()
Get the capacity of this animator's queue or -1 if the capacity is unlimited.
Returns:
The capacity of this animator's queue.
Throws:
IllegalStateException - Signals that this animator has terminated.

isQueueEmpty

public boolean isQueueEmpty()
Determine whether this animator's queue is empty.
Returns:
true if this animator's queue is empty.
Throws:
IllegalStateException - Signals that this animator has terminated.

getQueueSize

public int getQueueSize()
Get the current size of this animator's queue.
Returns:
The current size of this animator's queue.
Throws:
IllegalStateException - Signals that this animator has terminated.

getQueue

public List getQueue()
Get a list of event handler applications for this animator's queue. This method is useful for debugging because it enables a dump of an animator's queue.
Returns:
A list of event handler applications for this animator's queue.
Throws:
IllegalStateException - Signals that this animator has terminated.
See Also:
HandlerApplication


(C) Copyright 2001 UW CSE