Parallel Java (PJ) is an API and middleware for parallel programming in 100% Java on shared memory multiprocessor (SMP) parallel computers, cluster parallel computers, and hybrid SMP cluster parallel computers. PJ was developed by Professor Alan Kaminsky and his student Luke McOmber in the Department of Computer Science at the Rochester Institute of Technology.
I am happy to answer general questions about the Parallel Java Library, receive bug reports, and entertain requests for additional features. Please contact me by email at ark@cs.rit.edu. I regret that I am unable to provide technical support, specific installation instructions for your system, or advice about configuring your parallel computer hardware.
System Requirements
Installation
Usage
License
Revision History
PJ was developed using Java Development Kit (JDK) 1.5.0. PJ uses the generics, enumerations, concurrency utilities, and other Java language features introduced with JDK 1.5.0 and will not work with earlier JDK versions.
There are two versions of the PJ distribution, an executable distribution and a source distribution.
Executable distribution. The executable distribution comes in a Java Archive (JAR) file named "pjYYYYMMDD.jar", where YYYYMMDD are the year, month, and date. The executable distribution includes the PJ class files only. To install the executable distribution, simply store the JAR file somewhere. You may wish to change the file name, say to "pj.jar".
Source distribution. The source distribution comes in a Java Archive (JAR) file named "pjsrcYYYYMMDD.jar", where YYYYMMDD are the year, month, and date. The source distribution includes the PJ class files, source files, and documentation files (Javadoc). To install the source distribution, just unpack the JAR file. The source distribution expands into a subdirectory named "pj". If you already have a subdirectory of that name which you want to save, be sure to unpack the JAR file in some other directory. Documentation is stored under the directory "pj/doc"; point your HTML browser to that directory. Java source files and class files are stored under the directory "pj/lib".
Installation on a SMP computer. To run PJ programs on a shared memory multiprocessor (SMP) parallel computer, no further installation is required.
Installation on a cluster. To run PJ programs on a cluster parallel computer, in addition to installing the PJ JAR file, you must configure and run certain daemon processes on the frontend and backend processors of the cluster. For further information, see package edu.rit.pj.cluster.
Executable distribution. When compiling and executing Java programs that use PJ, if you have installed the executable distribution, you must set your classpath to include the PJ JAR file. Here is an example of a command for the bash shell to set the classpath to the current directory plus the PJ JAR file:
export CLASSPATH=.:/home/fac/ark/public_html/pj.jar
Here is an example of a command for the csh shell to set the classpath to the current directory plus the PJ JAR file:
setenv CLASSPATH .:/home/fac/ark/public_html/pj.jar
Source distribution. When compiling and executing Java programs that use PJ, if you have installed the source distribution, you must set your classpath to include the top-level directory under which PJ's Java class files are stored. Here is an example of a command for the bash shell to set the classpath to the current directory plus the PJ directory:
export CLASSPATH=.:/home/fac/ark/public_html/pj/lib
Here is an example of a command for the csh shell to set the classpath to the current directory plus the PJ directory:
setenv CLASSPATH .:/home/fac/ark/public_html/pj/lib
The documentation files, Java source files, and Java class files in the Parallel Java Library ("PJ") are copyright © 2005-2008 by Alan Kaminsky. All rights reserved. For further information, contact the author, Alan Kaminsky, at ark@cs.rit.edu.
PJ is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
PJ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is provided in the file gpl.txt. You may also obtain a copy of the GNU General Public License on the World Wide Web at http://www.gnu.org/licenses/gpl.html.
In package edu.rit.pj.cluster: Rewrote classes JobScheduler, Configuration, BackendInfo, and JobInfo to support clusters of single-CPU nodes and clusters of multi-CPU nodes. Eliminated classes HybridJobScheduler, HybridConfiguration, HybridBackendInfo, and HybridJobInfo. Changed class Configuration to include the number of CPUs in each backend node. As a consequence, this version of the Parallel Java cluster middleware will not interoperate with previous versions.
In package edu.rit.hyb.keysearch: A few revisions to class FindKeyHyb, a hybrid parallel program for AES partial key search.
In package edu.rit.hyb.fractal: Added class MandelbrotSetHyb, a hybrid parallel program to calculate an image of the Mandelbrot Set with one-level load balancing. Added class MandelbrotSetHyb2, a hybrid parallel program to calculate an image of the Mandelbrot Set with two-level load balancing.
In package edu.rit.hyb.network: Rewrote classes FloydRandom, FloydPrint, FloydSeq, and FloydHyb to use a DoubleMatrixFile to read and write the input and output files.
In package edu.rit.hyb.prime: Rewrote all the programs for calculating the prime counting function.
In class edu.rit.pj.Comm: Added the allToAll(), scan(), and exclusiveScan() collective communication operations. Removed the versions of the reduce() and allReduce() operations with separate source and accumulator buffers.
In class edu.rit.mp.Buf: Added the fill() and getTemporaryBuf() methods.
Fixed bugs in class edu.rit.pj.reduction.ReduceArrays; in each method, the number of array elements to reduce was one too large.
In package edu.rit.clu.antimatter: Changed the implementation of the pipelined AntiprotonClu3 program to use fewer interprocess connections.
In package edu.rit.image: Added class PJGHueImage for reading and writing image files where the image consists of a continuous range of hues. (The existing class PJGColorImage is best suited for images consisting of a small discrete set of colors.)
In the unnamed package: Fixed a bug in class mprun; under JDK 1.6, class ProcessBuilder requires the full pathname of the command to execute.
In package edu.rit.mp: Fixed bugs in classes ChannelGroup and NetworkChannelReceiveThread; several I/O error conditions were not handled properly.
In package edu.rit.util: Changed the implementation of class DefaultRandom so that close seed values do not give closely correlated random sequences.
In package edu.rit.pj.reduction: Changed the documentation of class ObjectOp to state the requirements for an object reduction operation, which are assumed by the other classes in the Parallel Java Library.
In package edu.rit.util: Fixed bugs in class Random; some precondition checks were missing.
In class edu.rit.pj.Comm: Reimplemented the flood and all-gather operations to reduce the number of message rounds.
In package edu.rit.smp.monte: Changed classes PiSmp, PiSmp2, and PiSmp3 to use a LongForLoop.
In package edu.rit.util: Changed the implementation of class Random. Changed class DefaultRandom to use a hashing algorithm instead of a multiplicative congruential generator (MCG) algorithm; the hashing algorithm avoids certain weaknesses of the MCG algorithm. The previous version of class DefaultRandom, which uses a MCG algorithm, is still available as class Mcg1Random.
In package edu.rit.mp.buf: Fixed bugs in the object buffer subclasses; the serialized representation was not reset in all cases when the buffer contents were changed. Fixed bugs in the matrix buffer subclasses; an ArithmeticException was thrown when receiving into a matrix buffer for a slice of zero columns.
In package edu.rit.numeric.plot.impl: Fixed a bug in class XYPlot; an exception was thrown when plotting a line for a data series with one data point.
In package edu.rit.smp.fractal: Changed classes MSHistogramSeq, MSHistogramSmp, MSHistogramSmp2, and MSHistogramSmp3 to print the histogram into a file.
In package edu.rit.numeric: Added class Cubic for solving cubic equations.
In package edu.rit.mp: Added a channel group ID to class ChannelGroup. Added methods to class Channel to obtain the channel group IDs of the near end channel group and the far end channel group. These changes were needed to fix the aforementioned bug.
In the unnamed package: Added the pjrun program; this lets a user run a non-PJ job on a PJ cluster, using the PJ job queue to assign backend nodes to the job.
In package edu.rit.smp.network: Changed all the programs to use class edu.rit.io.DoubleMatrixFile for input and output of the distance matrix files.
In package edu.rit.clu.network: Changed all the programs to use class edu.rit.io.DoubleMatrixFile for input and output of the distance matrix files. Changed class FloydClu so that each process reads a slice of the distance matrix from the input file and writes a slice of the distance matrix to a per-process output file.
In package edu.rit.clu.fractal: Rewrote class MandelbrotSetClu2. Added class MandelbrotSetClu3.
In package edu.rit.io: Fixed a bug in class Files; the fileForRank() method did not return the correct result if the argument was an absolute path.
In package edu.rit.mp: Changed interface ConnectListener to have separate methods for reporting near-end-initiated connections and far-end-initiated connections. Changed class ChannelGroup not to start listening for incoming connections until a new startListening() method is called. Changed class ChannelGroup to eliminate the methods that query for channels. These changes were needed to support the new hybrid job scheduler.
In package edu.rit.pj: Changed class Comm so that when one process initiates a connection to another process, the initiating process sends a message identifying the initiating process's rank. This change was needed to support the new hybrid job scheduler.
Changed several classes throughout the Library to use 128 extra padding bytes to avert cache interference, instead of 64. (128 bytes is the more prevalent cache line size in modern CPUs.)
In class edu.rit.numeric.plot.Plot: Made the class serializable. Added static methods to read and write Plot objects from and to files. Removed the display() and repaint() methods; their functionality is now available through the Viewable interface.
In package edu.rit.swing: Added interface Viewable which extends interface Displayable; to show itself on the screen, a Viewable object can return a DisplayableFrame. Drawings and plots are now Viewable objects. Changed class DisplayableFrame so that when it saves the displayable object in a PNG file, the object is saved at its zoomed size.
Rewrote package edu.rit.image. It now contains classes for 24-bit color images and 8-bit grayscale images in the Parallel Java Graphics (PJG) image file format. PJG image files are somewhat larger than, but take much less time to write than, PNG image files. For further information, see class PJGImage.
In the unnamed package: Added program PJG to display an image read from a PJG file.
In package edu.rit.smp.fractal: Updated the Mandelbrot Set SMP parallel programs to generate a PJG image file instead of a PNG image file.
In package edu.rit.clu.fractal: Updated the Mandelbrot Set cluster parallel programs to use the matrix allocation and deallocation operations in class edu.rit.util.Arrays and to generate a PJG image file instead of a PNG image file.
In package edu.rit.mp: Added a static emptyBuffer() factory method to each buffer subclass. Fixed a bug in class NetworkChannelReceiveThread; an incoming message was not received properly if the number of items in the message exceeded the number of items in the destination buffer. Removed the I/O completion hook and chained I/O request capabilities from class IORequest; these reduced message passing performance too much. Changed the non-blocking send and receive methods in class ChannelGroup to take an IORequest argument instead of creating their own new IORequest object.
In package edu.rit.pj: Removed enumeration Wait. In its place, added class BarrierAction to specify what should happen during a barrier synchronization. Changed all the execute() methods in class ParallelRegion to use class BarrierAction instead of enumeration Wait. In class Comm, changed the implementation of flood-receive to use a special subclass of class IORequest instead of an I/O completion hook.
In package edu.rit.draw.item: Added class Polygon.
In package edu.rit.mp: Fixed bugs in the factory methods in the buffer base classes; the factory methods would fail if a matrix row was not allocated; the factory methods were changed to return a zero-length buffer instead.
In package edu.rit.mp.buf: Moved precondition checks out of the buffer subclass constructors into the buffer base class factory methods in package edu.rit.mp.
In class edu.rit.pj.Comm: Added the host() method.
In class edu.rit.numeric.Plot: Added a "Format" menu to the plot window that lets the user change plot attributes interactively.
In class edu.rit.swing.DisplayableFrame: Added a "Fit Window" menu item to the "View" menu that resizes the window to fit the displayable object.
In package edu.rit.mp: Added the isFinished() method to class IORequest. Added I/O request chaining and I/O completion hook capabilities to class IORequest and class ChannelGroup. These are used to implement flood-send and flood-receive.
In package edu.rit.clu.keysearch: Changed the FindKeyClu2 program to use flood-send and flood-receive to stop the search when any process finds the key.
In the unnamed package: Added class Program1Clu, an introductory parallel program for a cluster.
In package edu.rit.pj.reduction: In each of the shared array classes, added a method to reduce a portion of the shared array with a portion of a given array.
In package edu.rit.pj: Added the team() and region() methods to class ParallelConstruct. Added the isExecutingInParallel() and region() method to class ParallelTeam. Changed the implementation of the parallel constructs' low-level thread synchronization to improve performance.
In package edu.rit.numeric.plot: Added the ability to specify bold, italic, superscript, and subscript text attributes in plot labels. Added the ability to draw a smooth curve for an X-Y data series.
In package edu.rit.draw.item: Added class Bow to draw curved (bowed) lines. Added class Oval to draw ovals. Added a round corner attribute to class Rectangle. Added class Group to permit a group of drawing items to be translated and rotated as a unit.
Consolidated packages edu.rit.pj.op and edu.rit.pj.shared into one package, edu.rit.pj.reduction. The new package has classes for thread safe shared reduction variables of each primitive type and of object types, and arrays thereof. The new package also has classes for binary reduction operators of each primitive type as well as object types. Shifted the getReductionBuf() method from class edu.rit.pj.op.Op to class edu.rit.mp.Buf.
In package edu.rit.util: Added a stride to classes Range and LongRange.
In packages edu.rit.mp and edu.rit.mp.buf: The factory methods for creating buffer objects are now in the base classes in package edu.rit.mp. Factory methods are provided for single items, arrays, matrices, thread safe shared items, and thread safe shared arrays of each primitive type and of object types. All the buffer classes for slices of arrays and matrices now support ranges with a stride of 1 and ranges with a stride greater than 1.
In package edu.rit.pj.cluster: Added class Configuration to encapsulate the cluster configuration file. Added the ability to specify JVM command line flags in the configuration file. Fixed a bug in class JobFrontend; the command to run a job backend process did not work if the working directory name contained whitespace.
Added package edu.rit.numeric with classes for numerical computation. Added packages edu.rit.numeric.plot and edu.rit.numeric.plot.impl with classes for creating plots, displaying them on the screen, and writing them to PNG or PostScript files.
In the unnamed package: Added programs Speedup and TimeFit for analyzing parallel program running time measurements.
Added package edu.rit.hyb.antimatter with hybrid SMP cluster parallel programs for simulating antiproton motion in an antiproton trap (classes AntiprotonHyb and RenderSeq).
In class edu.rit.pj.Comm: Rewrote the allGather() method to use a significantly faster message pattern. Rewrote the logic for connecting channels between backend processes. Added caching of message pattern information in the broadcast(), allGather(), and reduce() methods.
Removed package edu.rit.clu.particles; package edu.rit.clu.antimatter took its place.
In package edu.rit.clu.timing: Added class TimeSendDouble to measure the time required to send a message whose data items are type double.
In package edu.rit.clu.fractal: Fixed a bug in class MandelbrotSetClu4; the program did not properly overlap sending the previous slice and computing the next slice.
In package edu.rit.util: Fixed a bug in class Random; the nextInt() method could sometimes consume more than one value from the pseudorandom sequence, leading to incorrect sequence splitting in a parallel program.
In package edu.rit.clu.timing: Changed the output format for classes TimeSend and TimeBcast.
In class edu.rit.pj.PJProperties: Added the pj.jobtime Java system property to set the maximum running time for a job.
In package edu.rit.mp: Fixed a bug in class ChannelGroup; if one thread tried to send a message to another thread in the same process, a deadlock could happen.
In class edu.rit.pj.ParallelRegion: Added reductionArray() methods to create reduction variables containing arrays of the primitive types.
In package edu.rit.smp.network: Minor changes to the Floyd's Algorithm programs.
Removed obsolete package edu.rit.smp.sort.
Made some minor changes to the parallel programs in packages edu.rit.smp.fractal and edu.rit.smp.monte.
In package edu.rit.pj.cluster: Changed the frontend file I/O capability to reduce the number of byte array copy operations.
In package edu.rit.pj: Changed the name of class Status to class CommStatus to emphasize that the class stores the status of a communication operation in class Comm.
In package edu.rit.mp.buf: Added buffer classes for matrices of all primitive types. Added a buffer class for a matrix of objects.
Fixed a bug in class edu.rit.clu.particles.ProtonClu3; computation and communication used the same array, so incoming new data could overwrite the previous data being used in the computation.
In package edu.rit.clu.particles: Added more cluster parallel programs for the Particle Simulation, an N-bodies problem.
Added package edu.rit.vector with class Vector2D, a two-dimensional mathematical vector of doubles, as well as buffer classes for sending and receiving 2-D vectors in message passing parallel programs.
Added package edu.rit.clu.particles with sequential and cluster parallel programs for the Particle Simulation, an N-bodies problem.
Added package edu.rit.image. This package contains image classes equivalent to the ones in package edu.rit.matrix. However, to improve running times, the new image classes operate on primitive matrices (type byte[][] or int[][]) instead of the matrix classes.
In package edu.rit.mp.buf: Added matrix buffer classes equivalent to the ones in package edu.rit.matrix for byte, double, and integer matrices. However, to improve running times, the new matrix buffer classes operate on primitive matrices instead of the matrix classes.
In package edu.rit.mp.buf: The constructors in all the array buffer classes were deprecated, and static factory methods were added. The constructors are still available but should no longer be used. The constructors will be removed in a future release of the Parallel Java Library. The constructors were deprecated because the static factory methods provide greater programming flexibility.
Revised code throughout the Parallel Java Library not to use the deprecated classes and constructors.
Fixed a bug in class edu.rit.matrix.ByteMatrixBuf; the I/O buffer position was not set properly after sending items from or receiving items into the byte matrix buffer.
Added package edu.rit.pj.op with classes for binary operations to do parallel reduction in a message passing program.
Added package edu.rit.clu.network with cluster parallel programs for computing all shortest paths in a network using Floyd's Algorithm, an example of an algorithm that uses broadcasting on a cluster parallel computer.
Added package edu.rit.clu.monte with cluster parallel programs for computing π using a Monte Carlo technique, an example of an algorithm that uses reduction on a cluster parallel computer.
Fixed a bug in the matrix classes of package edu.rit.matrix; the row() method did not create a reference to the correct row if the full matrix was not allocated.
In package edu.rit.pj: Added class RangeSchedule for writing cluster parallel programs using the master-worker pattern.
In package edu.rit.clu.fractal: Added cluster parallel program MandelbrotSetClu2 that computes the Mandelbrot Set using the master-worker pattern for load balancing. Added cluster parallel program MandelbrotSetClu3 that computes the Mandelbrot Set using the master-worker pattern for load balancing and uses overlapped computation and I/O.
Fixed a bug in class edu.rit.pj.Comm; a deadlock could happen when a process did a receive from "any channel."
In package edu.rit.pj: Class Comm was changed to use class edu.rit.mp.Buf as the message buffer. Interface edu.rit.pj.Buffer and package edu.rit.pj.data were eliminated. Added the ability for a process to send and receive a message to and from itself in different threads. Added the scatter and gather collective communication methods.
In package edu.rit.matrix: Added classes ParallelIntegerMatrix, RowSliceIntegerMatrix, and IntegerMatrixBuf with methods for transferring integer matrices between processes using message passing.
Added package edu.rit.clu.fractal with cluster parallel programs for computing an image of the Mandelbrot Set, an example of a massively parallel problem that needs load balancing.
In package edu.rit.pj: Added send(), receive(), and broadcast() communication methods to class Comm. Added package edu.rit.pj.data with classes for message data buffers. Made many changes to package edu.rit.pj.cluster to support the new Comm capabilities.
Added package edu.rit.clu.keysearch with cluster parallel programs for breaking a block cipher using exhaustive key search, an example of a massively parallel problem.
Added package edu.rit.clu.timing with cluster parallel programs for timing the send, receive, and broadcast methods in class edu.rit.pj.Comm.
Fixed a bug in class edu.rit.pj.Lock; exclusive locking was not implemented properly. Fixed a bug in class edu.rit.pj.cluster.BackendClassLoader; improper thread synchronization sometimes caused a ClassCircularityError.
In package edu.rit.smp.sort: Redesigned the SwapSortSeq and SwapSortSmp programs. Added the SwapSortSmp2 program which does a parallel reduction using a reduction variable.
In package edu.rit.pj.cluster: Fixed a bug in class JobFrontend; the job frontend did not wait for end-of-stream on the SSH session's standard output and standard error before exiting.
Added package edu.rit.pj.cluster with message passing middleware classes for PJ message passing parallel programs.
In package edu.rit.pj: Added class Comm for using the message passing middleware in a PJ parallel program. At present, class Comm has a method for initializing the message passing middleware and running a PJ parallel program on the backend processors of a cluster parallel computer. In future releases, class Comm will include methods for message passing.
In package edu.rit.matrix: Added class SyncColorImage with producer-synchronization.
In package edu.rit.smp.fractal: Added class MandelbrotSetSmp2 with a program for computing an image of the Mandelbrot set that uses overlapped computation and I/O as well as a parallel loop.
In package edu.rit.matrix: Added classes for treating an integer matrix as a color image. Added classes for treating a byte matrix as an indexed color image.
Added package edu.rit.color with classes for representing colors in different ways.
Added package edu.rit.smp.fractal with programs for computing an image of the Mandelbrot Set, an example of a massively parallel problem that needs load balancing.
Added package edu.rit.crypto.blockcipher with classes for the Advanced Encryption Standard (AES) block cipher, used by the aforementioned programs.
Added package edu.rit.util with: class Range to represent a range of indexes; class HexPrintStream to print things in hexadecimal.
Added package edu.rit.matrix with: classes for one-dimensional arrays and matrices (two-dimensional arrays) of various data types; and classes for treating a byte matrix as a grayscale image.
In package edu.rit.pj.test: Added program UC to test parallel iterations.
In package edu.rit.pj.shared: Added several additional arithmetic methods to the shared variable wrapper classes.