Interface CQComparator

  • All Superinterfaces:
    java.util.Comparator
    All Known Implementing Classes:
    DoubleCQComparator, 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$
    Author:
    Lukito Muliadi, Edward A. Lee
    See Also:
    CalendarQueue, Comparator
    Pt.AcceptedRating:
    Yellow (liuj)
    Pt.ProposedRating:
    Green (eal)
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
    • 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.