Appendix

Benchmarks

JGL is a high performance library whose containers and algorithms meet or beat the performance of existing libraries. In addition, the JGL algorithms are generally at least as fast as their hand-coded equivalents. The JGL installation includes the following set of benchmarks:

  \jgl_1_1
    \benchmarks
      ArrayBenchmarks.java       Compares JGL Array against JDK Vector
      MapBenchmarks.java         Compares JGL Map against JDK Hashtable
      SortingBenchmarks.java     Compares JGL sort() against hand-coded quicksort
      *.txt                      Sample benchmarks

Sample benchmarks

To run these benchmarks, compile them in the benchmarks directory by typing:

  jvc *.java

and then run them by entering

  jview ArrayBenchmarks
  jview MapBenchmarks
  jview SortingBenchmarks

Each of these programs uses the Benchmark class to perform timing comparisons, and display intermediate benchmarks as they are gathered. The final performance ratio is displayed at the end of each benchmark. A ratio of less than 1.0 means that JGL ran faster. A sample run of these benchmarks is included in the files *.txt. A summary of these files is included on the next page.

Please note that random variations in the garbage collection system can cause significant variance in an individual performance statistic. The performance claims that we make for JGL are based on an average of large numbers of measurements.

SAMPLE BENCHMARKS
-----------------
These benchmarks were run on a Toshiba Tecra computer with 
32Mb RAM running Windows 95 and JDK 1.0.2.

A ratio of less than 1.0 means that JGL ran faster.

ArrayBenchmarks.txt
-------------------
ratio of jglArrayGetting to jdkVectorGetting is 0.850775
ratio of jglArrayPutting to jdkVectorPutting is 1.21103
ratio of jglArrayIterating to jdkVectorIterating is 1.12203
ratio of jglArrayAdding to jdkVectorAdding is 0.715431
ratio of jglArrayClearing to jdkVectorClearing is 0.204819
ratio of jglArrayInserting to jdkVectorInserting is 1.02515
ratio of jglArrayRemoving to jdkVectorRemoving is 0.980042

MapBenchmarks.txt
-----------------
ratio of jglMapAdding to jdkHashtableAdding is 0.983074
ratio of jglMapFinding to jdkHashtableFinding is 1.00821
ratio of jglMapRemoving to jdkHashtableRemoving is 1.02933
ratio of jglMapClearing to jdkHashtableClearing is 0.44186

SortingBenchmarks.txt
---------------------
ratio of jgl sort algorithm to handcoded sorting is 1.04997

A Comparison of JGL vs. STL

JGL takes advantage of the STL philosophy of separating containers from algorithms. It also embeds some of the most common algorithms directly into the JGL containers and supplies container-oriented versions of all algorithms. This approach allows JGL to be easy to use without losing the benefit of reusable algorithms.

This section lists the differences between JGL and STL as well as a side-by-side comparison of JGL and STL code segments.

Feature Enhancements

Here is a list of the feature that are in JGL but not in STL:

JGL containers can be accessed simultaneously by multiple threads without a problem.
JGL includes hashing maps and sets as well as ordered maps and sets.
JGL includes a singly linked list.
JGL Maps include an add() method that takes a key and a value.
JGL Maps include a put() method for easily replacing the value associated with a key.
JGL containers include additional methods for algorithms such as replace() and remove().
JGL sets directly support set operations such as union().
JGL lists support indexed access.
JGL includes additional function objects such as NegativeInteger.
JGL arrays support pushFront() and popFront().
JGL pop operations return the Object that is begin popped.
JGL sequential containers provide add() as a synonym for pushBack().
JGL supplies additional algorithms such as those in Printing.
JGL map iterators provide easy access to the key and value of their associated key/value pair.
JGL random access iterators provide the index() method for obtaining their index.
JGL random access containers provide indexed access to methods such as remove(), replace().
JGL supports heap functionality for bidirectional iterators as well as random access iterators.
JGL algorithms can operate directly on containers as well as iterator pairs.
JGL container iterators include the atBegin() and atEnd() testing methods.
JGL randomShuffle() works with bidirectional iterators.
JGL sort() can sort any kind of sequence.
JGL stacks and queues work with any sequence, whereas STL required random access sequences.

Compatibility Features

Here is a list of the features that JGL has for compatibility with existing Java code:

JGL algorithms can work on native arrays of objects and primitives as well as JGL containers.
JGL iterators are backwards compatible with the java.util.Enumeration interface.
JGL Arrays may be constructed to take ownership of a native array.
JGL uses standard Java exceptions whenever possible.
JGL maps extend the java.util.Dictionary abstract base class.
JGL calls the STL container vector Array to avoid a name clash with java.util.Vector.
JGL calls the hashing associative containers HashMap and HashSet.
JGL uses remove() instead of erase().
JGL calls the ordered associative containers OrderedMap and OrderedSet.

Differences

Here is a list of the differences between JGL and STL that will probably always remain:

JGL Sets and Maps return an Object from a failed insert() operation.
JGL maps and sets provide getComparitor() instead of key_comp(), value_comp().
JGL packages algorithms as public static methods of algorithm classes.
JGL does not include pointer_to_function function objects.
JGL does not need function object adapter functions.
Every JGL container implementsadd().

Code Comparisons

This section contains some code samples that illustrate some of the similarities and differences between JGL and STL.

Creating a Vector and performing some common functions.

STL/C++
vector<int> v;
v.push_back( 1 );
v.push_back( 3 );
v.push_back( 2 );
cout << v.front() << ", " << v.back() << endl;
replace( v.begin(), v.end(), 1, 3 );

JGL/Java
Array array = new Array();
array.pushBack( 1 ); // Could use array.add( 1 ) instead.
array.pushBack( 3 );
array.pushBack( 2 );
System.out.println( array.front() + ", " + array.back() );
array.replace( 1, 3 ); // Note that common functions are part of container interface.

Iterating through a container.

STL/C++
vector<int> v;
v.push_back( 1 );
v.push_back( 3 );
v.push_back( 2 );
for( vector<int>::iterator i = v.begin(); i != v.end(); i++ )
  cout << *I << endl;

JGL/Java
Array array = new Array();
array.pushBack( 1 );
array.pushBack( 3 );
array.pushBack( 2 );
for( ArrayIterator i = array.begin(); !i.equals( array.end() ); i.advance() )
  System.out.println( i.get() );

or (clearer and more efficient)

Array array = new Array();
array.pushBack( 1 );
array.pushBack( 3 );
array.pushBack( 2 );
Enumeration e = array.begin();
while( e.hasMoreElements() )
  System.out.println( e.nextElement() );

Iterating through a native array.

STL/C++
int array[] = { 1, 3, 2 };
for( int* p = array; p != array + 3; p++ )
  cout << *p << endl;

JGL/Java
int array[] = { 1, 3, 2 };
for( IntIterator p = IntIterator.begin( array ); p.hasMoreElements(); p.advance() )
  System.out.println( p.get() );

Sorting a container.

STL/C++
vector<int> v;
v.push_back( 1 );
v.push_back( 3 );
v.push_back( 2 );
sort( v.begin(), v.end() );

JGL/Java
Array array = new Array();
array.pushBack( new Integer( 1 ) );
array.pushBack( new Integer( 3 ) );
array.pushBack( new Integer( 2 ) );
Sorting.sort( array );

Sorting a native array.

STL/C++
int array[] = { 1, 3, 2 };
sort( array, array + 3 );

JGL/Java
int ints [] = { 1, 3, 2 };
IntArray array = new IntArray( ints );
Sorting.sort( array );

Contents

Class Summary