Appendix

Benchmarks

A Comparison of JGL vs. STL

JGL License Agreement

Changes since JGL 1.1

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_2_0
    \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:

  javac *.java

and then run them by entering

  java ArrayBenchmarks
  java MapBenchmarks
  java 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 for JGL 2.0
-----------------------------
These benchmarks were run on a Toshiba Tecra computer with 
48Mb RAM running Windows NT 4.0 and JDK 1.1 final release.

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

ArrayBenchmarks.txt
-------------------
ratio of jglArrayGetting to jdkVectorGetting is 0.97214216
ratio of jglArrayPutting to jdkVectorPutting is 0.91792065
ratio of jglArrayIterating to jdkVectorIterating is 1.2563047
ratio of jglArrayAdding to jdkVectorAdding is 0.6945063
ratio of jglArrayClearing to jdkVectorClearing is 0.0625
ratio of jglArrayInserting to jdkVectorInserting is 1.171401
ratio of jglArrayRemoving to jdkVectorRemoving is 0.9390602

MapBenchmarks.txt
-----------------
ratio of jglMapAdding to jdkHashtableAdding is 1.0936952
ratio of jglMapFinding to jdkHashtableFinding is 1.0753689
ratio of jglMapRemoving to jdkHashtableRemoving is 2.4360888
ratio of jglMapClearing to jdkHashtableClearing is 0.61538464

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

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 features 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 NegativeNumber.
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( new Integer( 1 ) ); // Could use array.add( new Integer( 1 ) ) instead.
array.pushBack( new integer( 3 ) );
array.pushBack( new Integer( 2 ) );
System.out.println( array.front() + ", " + array.back() );
array.replace( new Integer( 1 ), new Integer( 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( new Integer( 1 ) );
array.pushBack( new Integer( 3 ) );
array.pushBack( new Integer( 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( new Integer( 1 ) );
array.pushBack( new Integer( 3 ) );
array.pushBack( new Integer( 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 );

JGL License Agreement

A copy of the license agreement you agreed to before downloading the JGL software may be found in the doc directory of the installation in the file license.txt.

Contents Class Summary

Changes in 2.0

There have been several changes and bug fixes since the 1.1 release of JGL. Probably the biggest change is that it now requires a Java compiler that JDK 1.1 compatible. A full listing of the differences can be found in changes.txt in the doc directory.