ptolemy.domains.sdf.kernel
Class ArrayFIFOQueue

java.lang.Object
  ptolemy.domains.sdf.kernel.ArrayFIFOQueue

All Implemented Interfaces:

java.lang.Cloneable

public final class ArrayFIFOQueue
extends java.lang.Object
implements java.lang.Cloneable

A first-in, first-out (FIFO) queue with variable capacity and optional history. Objects are appended to the queue with the put() method, and removed from the queue with the take() method. The object removed is the oldest one in the queue. By default, the capacity is infinite, but it can be set to any nonnegative size. If the history capacity is greater than zero (or infinite, by setting the capacity to INFINITE_CAPACITY), then objects removed from the queue are transferred to a history queue rather than simply removed. By default, the history capacity is zero.

This queue is implemented as a circular array. When the array becomes full, it is transparently doubled in size.

Since:

Ptolemy II 0.2

Version:

$Id: ArrayFIFOQueue.java 59166 2010-09-21 17:05:27Z cxh $

Author:

Steve Neuendorffer, contributor: Brian Hudson

Accepted Rating:

Yellow (johnr)

Proposed Rating:

Yellow (neuendor)

Field Summary

private Nameable	_container The container, if there is one.
private int	_historyCapacity The capacity of the history queue, defaulting to zero.
private java.util.LinkedList	_historyList The list of objects recently removed from the queue.
private java.lang.Object[]	_queueArray The list of objects currently in the queue.
private int	_queueBack The location of the next place to remove from _queueArray.
private int	_queueFront The location of the next place to insert in _queueArray.
private int	_queueMaxCapacity The maximum capacity of the queue.
private int	_queueSize The number of elements in the queue.
static int	DEFAULT_CAPACITY The default capacity of the queue.
static int	DEFAULT_HISTORY_CAPACITY The default capacity of the history queue.
static int	INFINITE_CAPACITY Used to indicate that the size of the queue or the history queue is infinite.
static int	STARTING_ARRAYSIZE The starting size of the circular buffer, if the capacity is infinite.

Constructor Summary

ArrayFIFOQueue()
Construct an empty queue with no container, and an infinite capacity.

ArrayFIFOQueue(ArrayFIFOQueue model)
Copy constructor.

ArrayFIFOQueue(int size)
Construct an empty queue with no container and the given capacity.

ArrayFIFOQueue(Nameable container)
Construct an empty queue with the specified container.

ArrayFIFOQueue(Nameable container, int size)
Construct an empty queue with the specified container and the given size.

Method Summary

private void	_resizeArray(int newSize) Resize the internal circular array to have the given size.
void	clear() Clear this queue of any contained objects.
java.lang.Object	clone() Clone this queue.
java.util.List	elementList() Return a list containing all the elements in the queue, beginning with the oldest.
java.util.Enumeration	elements() Enumerate the objects in the queue, beginning with the oldest.
java.lang.Object	get(int offset) Return an object in the queue or history.
int	getCapacity() Return the queue capacity.
Nameable	getContainer() Return the container of the queue, or null if there is none.
int	getHistoryCapacity() Return the capacity of the history queue.
java.util.Enumeration	historyElements() Enumerate the objects in the history, which are the N most recent objects taken from the queue, beginning with the oldest, where N is less than or equal to the history capacity.
int	historySize() Return the number of objects in the history.
boolean	isEmpty() Return true if the number of objects in the queue is zero.
boolean	isFull() Return true if the number of objects in the queue equals the queue capacity.
boolean	put(java.lang.Object element) Put an object in the queue and return true if this will not cause the capacity to be exceeded.
boolean	putArray(java.lang.Object[] element) Put an array of objects in the queue and return true if this will not cause the capacity to be exceeded.
boolean	putArray(java.lang.Object[] element, int count) Put an array of objects in the queue and return true if this will not cause the capacity to be exceeded.
void	setCapacity(int capacity) Set queue capacity.
void	setContainer(Nameable container) Set the container of the queue.
void	setHistoryCapacity(int capacity) Set the capacity of the history queue.
int	size() Return the number of objects in the queue.
java.lang.Object	take() Remove the oldest object from the queue and return it.
void	takeArray(java.lang.Object[] objects) Remove the count oldest objects from the queue and return them.
void	takeArray(java.lang.Object[] objects, int count) Remove the count oldest objects from the queue and return them.

Methods inherited from class java.lang.Object

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

Field Detail

INFINITE_CAPACITY

public static final int INFINITE_CAPACITY

Used to indicate that the size of the queue or the history queue is infinite.

See Also:

Constant Field Values

DEFAULT_CAPACITY

public static final int DEFAULT_CAPACITY

The default capacity of the queue.

See Also:

Constant Field Values

STARTING_ARRAYSIZE

public static final int STARTING_ARRAYSIZE

The starting size of the circular buffer, if the capacity is infinite.

See Also:

Constant Field Values

DEFAULT_HISTORY_CAPACITY

public static final int DEFAULT_HISTORY_CAPACITY

The default capacity of the history queue.

See Also:

Constant Field Values

_container

private Nameable _container

The container, if there is one.

_queueMaxCapacity

private int _queueMaxCapacity

The maximum capacity of the queue.

_queueArray

private java.lang.Object[] _queueArray

The list of objects currently in the queue.

_queueFront

private int _queueFront

The location of the next place to insert in _queueArray.

_queueBack

private int _queueBack

The location of the next place to remove from _queueArray.

_queueSize

private int _queueSize

The number of elements in the queue.

_historyCapacity

private int _historyCapacity

The capacity of the history queue, defaulting to zero.

_historyList

private java.util.LinkedList _historyList

The list of objects recently removed from the queue.

Constructor Detail

ArrayFIFOQueue

public ArrayFIFOQueue()

Construct an empty queue with no container, and an infinite capacity.

ArrayFIFOQueue

public ArrayFIFOQueue(int size)

Construct an empty queue with no container and the given capacity.

Parameters:

size - The size of the queue.

ArrayFIFOQueue

public ArrayFIFOQueue(Nameable container)

Construct an empty queue with the specified container. The container is only used for error reporting.

Parameters:

container - The container of the queue.

ArrayFIFOQueue

public ArrayFIFOQueue(Nameable container,
                      int size)

Construct an empty queue with the specified container and the given size. The container is only used for error reporting.

Parameters:

container - The container of the queue.

size - The size of the queue.

ArrayFIFOQueue

public ArrayFIFOQueue(ArrayFIFOQueue model)

Copy constructor. Create a copy of the specified queue, but with no container. This is useful to permit enumerations over a queue while the queue continues to be modified. The objects in the queue themselves are not cloned.

Parameters:

model - The queue to be copied.

Method Detail

clear

public void clear()

Clear this queue of any contained objects.

clone

public java.lang.Object clone()

Clone this queue. The cloned queue has no container. The objects in the queue themselves are not cloned.

Overrides:

clone in class java.lang.Object

Returns:

A clone of this queue

elements

public java.util.Enumeration elements()

Enumerate the objects in the queue, beginning with the oldest.

Returns:

An enumeration of objects.

elementList

public java.util.List elementList()

Return a list containing all the elements in the queue, beginning with the oldest.

Returns:

A list of objects

get

public java.lang.Object get(int offset)
                     throws java.util.NoSuchElementException

Return an object in the queue or history. The object is not removed from the queue or history. If the offset argument is zero, return the oldest object in the queue. If the offset is 1, return the second oldest object, etc. If there is no such object in the queue (the offset is greater than or equal to the current queue size), throw an exception. If the argument is -1, return the most recent object that was put in the history. If the argument is -2, return the second most recent object in the history, etc. If there is no such object in the history (the history capacity is zero or the absolute value of the offset is greater than the current size of the history queue), throw an exception.

Parameters:

offset - The position of the desired object.

Returns:

The desired object in the queue or history.

Throws:

java.util.NoSuchElementException - If the offset is out of range.

getCapacity

public int getCapacity()

Return the queue capacity. This will be INFINITE_CAPACITY if the capacity is infinite.

Returns:

The capacity of the queue.

See Also:

setCapacity(int)

getContainer

public Nameable getContainer()

Return the container of the queue, or null if there is none.

Returns:

The container of the queue.

See Also:

setContainer(Nameable)

getHistoryCapacity

public int getHistoryCapacity()

Return the capacity of the history queue. This will be zero if the history mechanism is disabled and INFINITE_CAPACITY if the history capacity is infinite.

Returns:

The capacity of the history queue.

See Also:

setHistoryCapacity(int)

historyElements

public java.util.Enumeration historyElements()

Enumerate the objects in the history, which are the N most recent objects taken from the queue, beginning with the oldest, where N is less than or equal to the history capacity. If the history capacity is infinite, then the enumeration includes all objects previously taken from the queue. If the history capacity is zero, then return an empty enumeration.

Returns:

An enumeration of objects in the history.

historySize

public int historySize()

Return the number of objects in the history.

Returns:

The current number of objects in the history.

isEmpty

public boolean isEmpty()

Return true if the number of objects in the queue is zero.

Returns:

A boolean indicating whether the queue is empty.

isFull

public boolean isFull()

Return true if the number of objects in the queue equals the queue capacity.

Returns:

A boolean indicating whether the queue is full.

put

public boolean put(java.lang.Object element)

Put an object in the queue and return true if this will not cause the capacity to be exceeded. Otherwise, do not put the object in the queue and return false.

Parameters:

element - An object to be put in the queue.

Returns:

A boolean indicating success.

putArray

public boolean putArray(java.lang.Object[] element)

Put an array of objects in the queue and return true if this will not cause the capacity to be exceeded. Otherwise, do not put any of the object in the queue and return false.

Parameters:

element - An array of objects to be put in the queue.

Returns:

A boolean indicating success.

putArray

public boolean putArray(java.lang.Object[] element,
                        int count)

Put an array of objects in the queue and return true if this will not cause the capacity to be exceeded. Otherwise, do not put any of the object in the queue and return false. The specified number of objects from the array will be put in the queue.

Parameters:

element - An array of objects to be put in the queue.

count - The number of objects to be put in the queue.

Returns:

A boolean indicating success.

setCapacity

public void setCapacity(int capacity)
                 throws IllegalActionException

Set queue capacity. Use INFINITE_CAPACITY to indicate unbounded capacity (which is the default). If the current size of the queue exceeds the desired capacity, throw an exception.

Parameters:

capacity - The desired capacity.

Throws:

IllegalActionException - If the queue contains more objects than the proposed capacity or the proposed capacity is illegal.

See Also:

getCapacity()

setContainer

public void setContainer(Nameable container)

Set the container of the queue. The container is only used for error reporting.

Parameters:

container - The container of this queue.

See Also:

getContainer()

setHistoryCapacity

public void setHistoryCapacity(int capacity)
                        throws IllegalActionException

Set the capacity of the history queue. Use 0 to disable the history mechanism and INFINITE_CAPACITY to make the history capacity unbounded. If the size of the history queue exceeds the desired capacity, remove the oldest objects from the history queue until its size equals the proposed capacity. Note that this can be used to clear the history queue by supplying 0 as the argument.

Parameters:

capacity - The desired capacity of the history queue.

Throws:

IllegalActionException - If the desired capacity is illegal.

See Also:

getHistoryCapacity()

size

public int size()

Return the number of objects in the queue.

Returns:

The number of objects in the queue.

take

public java.lang.Object take()

Remove the oldest object from the queue and return it. If there is no such object in the queue (the queue is empty), throw an exception. If the history mechanism is enabled, then put the taken object in the history queue. If the capacity of the history queue would be exceeded by this, then first remove the oldest object in the history queue.

Returns:

An object from the queue.

Throws:

java.util.NoSuchElementException - If the queue is empty.

takeArray

public void takeArray(java.lang.Object[] objects)
               throws java.util.NoSuchElementException

Remove the count oldest objects from the queue and return them. If there is no such object in the queue (the queue is empty), throw an exception. If the history mechanism is enabled, then put the taken object in the history queue. If the capacity of the history queue would be exceeded by this, then first remove the oldest object in the history queue.

Parameters:

objects - An array of objects from the queue.

Throws:

java.util.NoSuchElementException - If the queue is empty.

takeArray

public void takeArray(java.lang.Object[] objects,
                      int count)
               throws java.util.NoSuchElementException

Remove the count oldest objects from the queue and return them. If there is no such object in the queue (the queue is empty), throw an exception. If the history mechanism is enabled, then put the taken object in the history queue. If the capacity of the history queue would be exceeded by this, then first remove the oldest object in the history queue.

Parameters:

objects - An array of objects from the queue.

count - The number of objects to return.

Throws:

java.util.NoSuchElementException - If the queue is empty.

_resizeArray

private void _resizeArray(int newSize)

Resize the internal circular array to have the given size.

Throws:

InternalErrorException - If the proposed size is greater than the declared maximum size, or if the queue contains more objects than the proposed size or the proposed size is illegal.