ptolemy.actor.util
Interface CQComparator

All Superinterfaces:

java.util.Comparator

All Known Implementing Classes:

DECQEventQueue.DECQComparator, TimedEvent.TimeComparator, TMEventComparator

public interface CQComparator
extends java.util.Comparator

This interface extends the java.util.Comparator interface, which defines the compare() method. The extension defines additional methods that specifically support the CalendarQueue class. That class needs to associate an entry in the queue with a virtual bin number, and needs to be able to periodically recompute the width of its bins. Thus, merely being able to compare entries is not sufficient.

Since:

Ptolemy II 0.2

Version:

$Id: CQComparator.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Lukito Muliadi, Edward A. Lee

See Also:

CalendarQueue, Comparator

Accepted Rating:

Yellow (liuj)

Proposed Rating:

Green (eal)

Method Summary

long	getVirtualBinNumber(java.lang.Object entry) Given an entry, return a virtual bin number for the entry.
void	setBinWidth(java.lang.Object[] entryArray) Given an array of entries, set an appropriate bin width for a calendar queue to hold these entries.
void	setZeroReference(java.lang.Object zeroReference) Set the zero reference, to be used in calculating the virtual bin number.

Methods inherited from interface java.util.Comparator

compare, equals

Method Detail

getVirtualBinNumber

long getVirtualBinNumber(java.lang.Object entry)

Given an entry, return a virtual bin number for the entry. The virtual bin number is a quantized version of whatever key is being used to compare entries. The calculation performed should be something like:

(entry - zeroReference) / binWidth,

with the result cast to long.

Because of the way this is used by CalendarQueue, it is OK to return the low order 64 bits of the result if the result does not fit in 64 bits. The result will be masked anyway to get fewer low order bits that represent the bin number. As a net result, time stamps that differ by exactly 2^64 times the time resolution will appear in the event queue to be occurring at the same time.

Classes that implement this interface will in general need to perform a downcast on the arguments (of type Object) to the appropriate user defined classes. If the arguments are not of appropriate type, the implementation should throw a ClassCastException.

Parameters:

entry - An object that can be inserted in a calendar queue.

Returns:

The index of the bin.

setBinWidth

void setBinWidth(java.lang.Object[] entryArray)

Given an array of entries, set an appropriate bin width for a calendar queue to hold these entries. This method assumes that the entries provided are all different, and are in increasing order. Ideally, the bin width is chosen so that the average number of entries in non-empty bins is equal to one. If the argument is null set the default bin width.

Parameters:

entryArray - An array of entries.

setZeroReference

void setZeroReference(java.lang.Object zeroReference)

Set the zero reference, to be used in calculating the virtual bin number.

Parameters:

zeroReference - The starting point for bins.