Appendix

Benchmarks

A Comparison of JGL vs. STL

JGL License Agreement

Changes since JGL 2.0.x

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 pretty close in speed to their hand-coded equivalents. The JGL installation includes the following set of benchmarks:

`\jgl3.1.0`
	`\benchmarks`
		`ArrayBenchmarks.java`	Compares JGL `Array` against `java.util.Vector`.
		`MapBenchmarks.java`	Compares JGL `HashMap` against `java.util.Hashtable`.
		`SortingBenchmarks.java`	Compares JGL `Sorting.sort()` against hand-coded quicksort.
		`*.txt`	Sample benchmark output.

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 follows.

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. The JGL containers are also synchronized for greater thread safety (unlike the JDK containers), which has a small performance hit.


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 being 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 \jgl3.1.0 directory of the installation in the file license.txt.

Changes in 3.x

There have been several changes and bug fixes since the 2.0.x release of JGL. The most visible change is the new package layout, and the inclusion of distributed containers for use with ObjectSpace Voyager. A full listing of the differences can be found in changes.txt in the \jgl3.1.0\doc directory.

Contents

Class Summary