ports/openmpi
ports/openmpi
1
1
Форкнуть 0
Код Релизы Активность

Improved README.JAVA; remove README file in java directory

Просмотр исходного кода 
This commit was SVN r29289.
Этот коммит содержится в:
Jose Roman 2013-09-29 10:22:38 +00:00
родитель 72c9c66396
Коммит f656c9859c
2 изменённых файлов: 176 добавлений и 890 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

193
README.JAVA.txt
Просмотреть файл

@ -1,5 +1,3 @@
Feb 10, 2012
---------------
***************************************************************************
IMPORTANT NOTE
@ -9,19 +7,29 @@ JAVA SUPPORT IS NOT REQUIRED BY THE STANDARD. CONTINUED INCLUSION OF
THE JAVA BINDINGS IS CONTINGENT UPON ACTIVE USER INTEREST AND
CONTINUED DEVELOPER SUPPORT.
THIS SPECIFIC JAVA INTERFACE IS EXPERIMENTAL, INCOMPLETE (at least at
this time), AND SUBJECT TO CHANGE!
***************************************************************************
This version of Open MPI provides support for Java-based
MPI applications. At the time of this writing, not all MPI functions
are supported. However, work on extending the Java bindings to
provide full MPI coverage is underway.
MPI applications.
The rest of this document provides step-by-step instructions on
building OMPI with Java bindings, and compiling and running
Java-based MPI applications
Java-based MPI applications. Also, part of the functionality is
explained with examples. Further details about the design,
implementation and usage of Java bindings in Open MPI can be found
in [1]. The bindings follow a JNI approach, that is, we do not
provide a pure Java implementation of MPI primitives, but a thin
layer on top of the C implementation. This is the same approach
as in mpiJava [2]; in fact, mpiJava was taken as a starting point
for Open MPI Java bindings, but they were later totally rewritten.
[1] O. Vega-Gisbert, J. E. Roman, and J. M. Squyres. "Design and
implementation of Java bindings in Open MPI". In preparation
(2013).
[2] M. Baker et al. "mpiJava: An object-oriented Java interface to
MPI". In Parallel and Distributed Processing, LNCS vol. 1586,
pp. 748-762, Springer (1999).
============================================================================
@ -56,19 +64,19 @@ configuration.
In summary, therefore, you can configure the system using the
following Java-related options:
./configure --with-platform=contrib/platform/hadoop/<your-platform>
$ ./configure --with-platform=contrib/platform/hadoop/<your-platform>
...
or
./configure --enable-mpi-java --with-jdk-bindir=<foo>
--with-jdk-headers=bar ...
$ ./configure --enable-mpi-java --with-jdk-bindir=<foo>
--with-jdk-headers=<bar> ...
or simply
./configure --enable-mpi-java ...
$ ./configure --enable-mpi-java ...
if jdk is in a "standard" place that we automatically find.
if JDK is in a "standard" place that we automatically find.
----------------------------------------------------------------------------
@ -82,7 +90,7 @@ line using the --showme option, if you are interested.
Once your application has been compiled, you can run it with the
standard "mpirun" command line:
mpirun <options> java <your-java-options> <my-app>
$ mpirun <options> java <your-java-options> <my-app>
For convenience, mpirun has been updated to detect the "java" command
and ensure that the required MPI libraries and class paths are defined
@ -93,8 +101,159 @@ either on the command line or via the CLASSPATH environmental
variable. Note that the local directory will be added to the class
path if nothing is specified.
As always, the "java" executable, all required libraries, and your application classes
must be available on all nodes.
As always, the "java" executable, all required libraries, and your
application classes must be available on all nodes.
----------------------------------------------------------------------------
Basic usage of Java bindings
There is an MPI package that contains all classes of the MPI Java
bindings: Comm, Datatype, Request, etc. These classes have a direct
correspondence with classes defined by the MPI standard. MPI primitives
are just methods included in these classes. The convention used for
naming Java methods and classes is the usual camel-case convention,
e.g., the equivalent of MPI_File_set_info(fh,info) is fh.setInfo(info),
where fh is an object of the class File.
Apart from classes, the MPI package contains predefined public attributes
under a convenience class MPI. Examples are the predefined communicator
MPI.COMM_WORLD or predefined datatypes such as MPI.DOUBLE. Also, MPI
initialization and finalization are methods of the MPI class and must
be invoked by all MPI Java applications. The following example illustrates
these concepts:
import mpi.*;
class ComputePi {
public static void main(String args[]) throws MPIException {
MPI.Init(args);
int rank = MPI.COMM_WORLD.getRank(),
size = MPI.COMM_WORLD.getSize(),
nint = 100; // Intervals.
double h = 1.0/(double)nint, sum = 0.0;
for(int i=rank+1; i<=nint; i+=size) {
double x = h * ((double)i - 0.5);
sum += (4.0 / (1.0 + x * x));
}
double sBuf[] = { h * sum },
rBuf[] = new double[1];
MPI.COMM_WORLD.reduce(sBuf, rBuf, 1, MPI.DOUBLE, MPI.SUM, 0);
if(rank == 0) System.out.println("PI: " + rBuf[0]);
MPI.Finalize();
}
}
----------------------------------------------------------------------------
Exception handling
Java bindings in Open MPI support exception handling. By default, errors
are fatal, but this behavior can be changed. The Java API will throw
exceptions if the MPI.ERRORS_RETURN error handler is set:
MPI.COMM_WORLD.setErrhandler(MPI.ERRORS_RETURN);
If you add this statement to your program, it will show the line
where it breaks, instead of just crashing in case of an error.
Error-handling code can be separated from main application code by
means of try-catch blocks, for instance:
try
{
File file = new File(MPI.COMM_SELF, "filename", MPI.MODE_RDONLY);
}
catch(MPIException ex)
{
System.err.println("Error Message: "+ ex.getMessage());
System.err.println(" Error Class: "+ ex.getErrorClass());
ex.printStackTrace();
System.exit(-1);
}
----------------------------------------------------------------------------
How to specify buffers
In MPI primitives that require a buffer (either send or receive) the
Java API admits a Java array. Since Java arrays can be relocated by
the Java runtime environment, the MPI Java bindings need to make a
copy of the contents of the array to a temporary buffer, then pass the
pointer to this buffer to the underlying C implementation. From the
practical point of view, this implies an overhead associated to all
buffers that are represented by Java arrays. The overhead is small
for small buffers but increases for large arrays.
An alternative is to use "direct buffers" provided by standard
classes available in the Java SDK such as ByteBuffer. For convenience
we provide a few static methods "new[Type]Buffer" in the MPI class
to create direct buffers for a number of basic datatypes. Elements
of the direct buffer can be accessed with methods put() and get(),
and the number of elements in the buffer can be obtained with the
method capacity(). This example illustrates its use:
int myself = MPI.COMM_WORLD.getRank();
int tasks = MPI.COMM_WORLD.getSize();
IntBuffer in = MPI.newIntBuffer(MAXLEN * tasks),
out = MPI.newIntBuffer(MAXLEN);
for(int i = 0; i < MAXLEN; i++)
out.put(i, myself); // fill the buffer with the rank
Request request = MPI.COMM_WORLD.iAllGather(
out, MAXLEN, MPI.INT, in, MAXLEN, MPI.INT);
request.waitFor();
request.free();
for(int i = 0; i < tasks; i++)
{
for(int k = 0; k < MAXLEN; k++)
{
if(in.get(k + i * MAXLEN) != i)
throw new AssertionError("Unexpected value");
}
}
Direct buffers are available for: BYTE, CHAR, SHORT, INT, LONG,
FLOAT, and DOUBLE. There is no direct buffer for booleans.
Direct buffers are not a replacement for arrays, because they have
higher allocation and deallocation costs than arrays. In some
cases arrays will be a better choice. You can easily convert a
buffer into an array and vice versa.
All non-blocking methods must use direct buffers and only
blocking methods can choose between arrays and direct buffers.
The above example also illustrates that it is necessary to call
the free() method on objects whose class implements the Freeable
interface. Otherwise a memory leak is produced.
----------------------------------------------------------------------------
Specifying offsets in buffers
In a C program, it is common to specify an offset in a array with
"&array[i]" or "array+i", for instance to send data starting from
a given positon in the array. The equivalent form in the Java bindings
is to "slice()" the buffer to start at an offset. Making a "slice()"
on a buffer is only necessary, when the offset is not zero. Slices
work for both arrays and direct buffers.
import static mpi.MPI.slice;
...
int numbers[] = new int[SIZE];
...
MPI.COMM_WORLD.send(slice(numbers, offset), count, MPI.INT, 1, 0);
----------------------------------------------------------------------------

873
ompi/mpi/java/README.txt
Просмотреть файл

@ -1,873 +0,0 @@
This set of Java bindings was originally derived from mpiJava v1.2.7:
http://sourceforge.net/projects/mpijava/
The 1.2.7 tarball was uploaded to SourceForce on April 8, 2011
(although the README in the 1.2.7 tarball claims that it is version
1.2.5, and is dated January 2003).
There are home pages on the internet for "mpiJava" that might well be
ancestors of this project:
http://www.hpjava.org/mpiJava.html
http://aspen.ucs.indiana.edu/pss/HPJava/mpiJava.html
The source code and configure/build system have been heavily modified
to be in Open MPI.
The README file from the original 1.2.7 tarball is included below.
The License.txt file the 1.2.7 tarball is included in this directory.
=========================================================================
mpiJava - A Java Interface to MPI
---------------------------------
Version 1.2.5, January 2003
Bryan Carpenter, Sung Hoon Ko, Sang Boem Lim
Pervasive Technology Labs, Indiana University
email {shko,slim,dbc}@grids.ucs.indiana.edu
Xinying Li
Syracuse University
Mark Baker
CSM, University of Portsmouth
email mark.baker@computer.org
This package provides an object-oriented Java interface to the Message
Passing Interface (MPI) standard, for use on parallel or distributed
computing platforms. The release includes the Java Native Interface
(JNI) C stubs that binds the Java interface to an underlying native MPI
C interface (which must be obtained and installed independently). The
release also includes a comprehensive test suite for the Java
interface, created by translating the IBM MPI test suite to Java.
It includes some simple examples and demos.
The Java API is defined in the document "mpiJava 1.2: API specification"
in the `doc/' directory.
Platforms
---------
We have tested this release on the platforms listed below.
For the marked configurations, please note remarks in later sections
of this README. Some platforms need special configuration options for
the native MPI. All test cases and examples in this release have been run
on all platforms. Except for few occasions where programs completed but
terminated awkwardly, no failures were observed, provided the recommended
configuration was followed.
Operating System Java Native MPI
Redhat Linux 7.3 Sun SDK 1.4.1 MPICH 1.2.5
Redhat Linux 7.3 Sun SDK 1.4.1 LAM 6.5.8
Redhat Linux 7.3 IBM JDK 1.4.0 MPICH 1.2.4 (*)
Redhat Linux 7.3 IBM JDK 1.4.0 LAM 6.5.8 (*)
SunOS 5.8 Sun SDK 1.4.1 SunHPC-MPI 4
SunOS 5.8 Sun SDK 1.4.1 MPICH 1.2.5 (*)
SunOS 5.8 Sun SDK 1.4.1 LAM 6.5.8 (*)
AIX 3.4 IBM JDK 1.3.0 IBM MPI (SP2/3)
The software was also tested on the following platform, but occasional
intermittent failures were observed:
AIX 3.4 IBM JDK 1.3.0 MPICH 1.2.5 (*)
See the file TEST_REPORTS for more information.
(*): Note the remarks in the section below on MPI configuration options.
Of course it is possible to build mpiJava on other platforms, but expect
to do some trouble-shooting.
At various times we have successfully tested versions of this software
using combinations of systems including:
1. Operating systems:
Sun Machines running SunOS 5.4 (Solaris2.5.1)
Redhat Linux 7.3
AIX
WinTel NT 4 (SP3)
SGI Challange Machines running IRIX 6.2
2. Java Development environments:
Sun SDK 1.4(Linux, Solaris)
IBM Developer Kit for Linux, J2RE 1.4.0
AIX JDK 1.3
Java JDK 1.1.x(SGI)
3. Native MPI installations:
MPICH 1.2.5
SunHPC-MPI(4.0)
IBM POE
WMPI 1.1
Users have reported ports to other platforms (for Alpha processors, see
the message at the end of this file).
Updates and further information about mpiJava can be found on the home
page, `www.hpjava.org/mpiJava.html'.
If you find bugs, have comments, or want further information about
mpiJava or the team of developers, email `dbcarpen@indiana.edu' or
`sblim@indiana.edu'.
Installation
------------
The following instructions apply to UNIX.
[Some earlier releases of mpiJava have been tested on Windows NT. This
release has *not*. For old instructions on installation under Windows NT,
see the file `NT_INSTALL.TXT'. Because recent releases of mpiJava haven't
been tested on that platform, those instructions will certainly need
updating---we leave this option available for "experts" only.]
1. Install your preferred Java programming environment.
For Solaris and Linux, we strongly recommend to use JDK 1.4 or later.
This release provides a signal-chaining feature that can be used to
avoid some unpleasant non-deterministic bugs encountered with previous
releases of mpiJava.
After Java JDK is installed successfully, you should add the Java JDK
`bin' directory to your path setting, so that the `mpiJava/configure'
script can find the `java', `javac', and `javah' commands.
2. Install your preferred MPI software.
Add the MPI `bin' directory to your path setting. Test the MPI
installation before attempting to install mpiJava!
(See the "Recommended MPI configuration options" sections below,
for some recommended options when installing MPI.)
3. Now, you are ready to install the mpiJava interface.
step 1. Unpack the software, eg
gunzip -c mpiJava-x.x.x.tar.gz | tar -xvf -
A subdirectory `mpiJava/' is created.
step 2. Go to the `mpiJava/' directory. Configure the software for
your platform:
./configure
You may specify various standard options to the configure
process.
Try
./configure --help
for various option.
The default MPI is MPICH. Use
./configure --with-MPI=lam
for LAM. Use
./configure --with-MPI=sunhpc
for SunHPC. Use
./configure --with-MPI=sp2
for AIX + POE.
step 3. Build (compile) the software:
make
After successful compilation, the makefile will put the generated class
files in directory `lib/classes/mpi/', and also place a native dynamic
library in directory `lib/'. Now:
Add the directory `<mpiJava-pathname>/src/scripts' to your path environment
variable.
Add the directory `<mpiJava-pathname>/lib/classes' to your CLASSPATH
environment variable.
Add the directory `<mpiJava-pathname>/lib' to your LD_LIBRARY_PATH
(Linux, Solaris, etc) or LIBPATH (AIX) environment variable.
(Some of these variables may be unnecesary if you are using the
`prunjava' script.)
step 4. Test the installation:
make check
NOTE: Several of the the scripts in this release assume your target
machines share user directories (presumably through NFS or equivalent),
and have compatible system commands *and library files* installed on
all nodes (e.g. in `/usr/lib'). Although it is possible to adapt the
basic mpiJava software to more heterogeneous situations, you will need
to do more work!
Using the software
------------------
If everything goes well, you can compile and run the test programs by
issuing the command
make check
in the mpiJava installation directory.
An example of how to compile and run a program:
javac Life.java
prunjava 4 Life
The `prunjava' script is a wrapper for the various MPI run commands.
The first argument is the number of processors on which the program will be
executed. A list of available host computers may be given in an
MPICH-style `machines' file in the local directory.
The `prunjava' script is provided mainly for purposes of testing. It is
not very general and in real situations you will often have to modify
this script, or start the program directly using the native MPI run
commands to achieve the effect you need.
With MPICH on some platforms you may be able to run mpiJava programs by
mpirun <mpirun options> java <java command arguments>
With this approach, you may be responsible for ensuring the remote
environment is set up correctly, e.g. by setting appropriate class
paths and library paths in your `.cshrc', `.bashrc', etc, on the remote
machines (the `prunjava' script adopts a different approach it
dynamically creates a script that sets up the required environment and
invokes the `java' command. This script is run across nodes using
`mpirun'.)
On SP2 you might run mpiJava by
poe java <java command arguments> <poe options>
Some MPI environments (SunHPC 4.0) may require that the native MPI library
be preloaded into the executable command---it may not be possible to
load the native `libmpi' with the Java `System.loadLibrary()' method.
Preloading can be achieved in Solaris or Linux by setting the LD_PRELOAD
environment variable. So for example with SunHPC you may start mpiJava by:
LD_PRELOAD=/opt/SUNWhpc/lib/libmpi.so
export LD_PRELOAD
mprun <mprun options> java <java command arguments>
(It is best to restrict of the LD_PRELOAD variable scope
by defining it only within a script, like our `prunjava'. Otherwise the
library may get loaded into *every* executable you run!
For reliable operation you should also add the `libjsig' library, where
available, to the LD_PRELOAD variable. See the notes below. Check the
source of the `mpiJava/src/scripts/prunjava' script for examples.)
API
---
The API definition is in
mpiJava/doc/api/mpi/mpiJava-spec.ps
Javadoc documentation for the API is preinstalled at
mpiJava/doc/api/mpi/package-summary.html
For questions and comments, email us.
Recommended MPI configuration options
-------------------------------------
In many case mpiJava will work using default MPI options. But after
much experimentation the options recommended below have been found to
eliminate certain failure modes. See the technical notes below for
more discussion.
Note all `configure' options specified in this section are for MPICH
or LAM `configure' scripts, *not* mpiJava!
1) Redhat Linux 7.3 + Sun SDK 1.4.1 + MPICH 1.2.5
Default
2) Redhat Linux 7.3 + Sun SDK 1.4.1 + LAM 6.5.6
Default is recommended.
If, however, problems are encountered, you may try reconfiguring LAM to
use a different signal, e.g.:
./configure ... --with-signal=SIGIO
3) Redhat Linux 7.3 + IBM 1.4 Java for Linux + MPICH 1.2.4
MPICH must be configured to use a signal other than the default SIGUSR1,
e.g.:
./configure ... -listener_sig=SIGIO
4) Redhat Linux 7.3 + IBM 1.4 Java for Linux + LAM 6.5.8
LAM must be configured to use a signal other than the default SIGUSR2,
e.g.:
./configure ... --with-signal=SIGIO
5) SunOS 5.8 + Sun SDK 1.4.1 + SunHPC-MPI 4
Default.
6) SunOS 5.8 + Sun SDK 1.4.1 + MPICH 1.2.4
Use:
./configure ... -cflags=-D_REENTRANT
(Note: on Solaris mpiJava has been tested with MPICH built using cc.)
7) SunOS 5.8 + Sun SDK 1.4.1 + LAM 6.5.6
Use:
./configure ... --with-cflags=-D_REENTRANT
8) AIX 3.4 + IBM JDK 1.3.0 Java + IBM MPI (SP2/3)
Default
9) AIX 3.4 + IBM JDK 1.3.0 Java + MPICH 1.2.5
Use:
./configure ... -cflags=-D_THREAD_SAFE
Note however that certain test cases have been observed to intermittently
hang on this platform for unknown reasons. It's use is not recommended.
(Note: on AIX mpiJava has been tested with MPICH built using cc.)
Technical Notes
===============
The following technical notes and case studies are largely for the benefit
of people trying to port mpiJava to other platforms, but in some cases
they also bear on the required configuration of the native MPI...
Problems with Signal Handlers (mpiJava 1.2.5)
---------------------------------------------
A problem in porting mpiJava to different platforms is conflicts in
uses of OS signal handlers by the Java Virtual Machine (and Java
libraries) and by the native MPI implementation.
Typical JVMs make use of OS signals and signal-handlers internally.
Typical MPI implementations override the default signal handlers.
If suitable measures are not taken, the MPI may blindly override the
signal-handlers installed by the JVM, leading to failures.
If you are using Sun's Java, we recommended to upgrade to JDK 1.4,
and set the environment variable `LD_PRELOAD' described in
http://java.sun.com/j2se/1.4/docs/guide/vm/signal-chaining.html
For example:
export LD_PRELOAD=$JAVA_HOME/jre/lib/$JARCH/$VM/libjsig.so
This resolves various intermittent bugs reported with previous versions
of mpiJava (on many important platforms).
In some cases this option is not sufficient or not available. Sometimes
it is nevertheless possible to work around problems by saving the signal
handlers installed by JVM, and restoring them after the MPI has overriden
them. The current release of mpiJava introduces a second native library
for saving and restoring relevant signal handlers. In other cases it may
be possible and/or necessary to reconfigure MPI to use a "safe" signal.
[In the following notes we have tried to give plausible causes for
observed problems. But appearances can be deceptive and we don't always
have access to sources of the software concerned; even where we do,
it can be very labour intensive to trace intermittent failure modes
in detail. Nevertheless we hope the workarounds we found may suggest
ones that work in other situations.]
KNOWN SIGNAL-HANDLING ISSUES for specific platforms, with workarounds:
The workarounds are configured in automatically for mpiJava 1.2.5 where
appropriate, but in some cases you may have to change your native MPI
configuration to avoid conflicting signals.
1) Redhat Linux 7.3 + Sun SDK 1.4.1 + MPICH 1.2.5
Hotspot sometimes deliberately throws and catches SIGSEGV and
similar signals. `MPI_Init' overrides the JVM signal handlers
leading to intermittent failures (especially in complex recursive
code, like object serialization). With earlier versions of JDK
many mpiJava programs ran successfully despite this conflict.
JDK 1.4 signal-chaining using `libjsig' resolves all remaining issues
we are aware of. This is configured automatically into the mpiJava
1.2.5 `prunjava' script, if mpiJava is built with JDK 1.4.
2) Redhat Linux 7.3 + Sun SDK 1.4.1 + LAM 6.5.6
We expect the same issues with SIGSEGV, etc as in MPICH case, which
should be resolved by using `libjsig'.
Additionally, there is a special problem with SIGUSR2, which causes
frequent, intermittent hanging of mpiJava programs. Just loading
`libjsig' doesn't resolve this problem (the signal handlers don't
seem to chain properly?) We found empirically that restoring the
original JVM signal handler for SIGUSR2 after `MPI_Init' eliminated
problems in all our test cases. This approach is automatically
configured into mpiJava 1.2.5.
An alternative solution is to configure LAM to use a signal
that Hotspot doesn't use, e.g.:
./configure ... --with-signal=SIGIO
(Note well this is the `configure' script for LAM, *not* mpiJava!
We randomly suggested SIGIO as the alternate signal.)
3) Redhat Linux 7.3 + IBM 1.4 Java for Linux + MPICH 1.2.4
The IBM classic JVM uses SIGUSR1, and (we found) may block this signal
during JNI calls. By default MPICH (on the default P4 device) uses
SIGUSR1 as its listener signal. This conflict causes most mpiJava
programs to hang. The only known solution is to to configure MPICH
to use a different signal, e.g:
./configure ... -listener_sig=SIGIO
(Note well this is the `configure' script for MPICH, *not* mpiJava!
We randomly suggested SIGIO rather than the more obvious SIGUSR2.
SIGUSR2 mostly worked, but apparently produced conflicts in GUI-based
example codes.)
This resolves all problems we are currently aware of.
4) Redhat Linux 7.3 + IBM 1.4 Java for Linux + LAM 6.5.8
We had some success. But the `tests/signals/' test case and
`examples/Nozzle', `examples/potts' examples hang on some of our
installations. Configuring LAM to use e.g. SIGIO -- see 2), above
-- appeared to help, but we aren't certain this is a complete
solution -- we had conflicting experiences.
For now this configuration should be considered experimental.
5) SunOS 5.8 + Sun SDK 1.4.1 + SunHPC-MPI 4
Comments similar to the Linux MPICH case, 1). No known problems
provide the `libjsig' signal interception library is loaded.
6) SunOS 5.8 + Sun SDK 1.4.1 + MPICH 1.2.5
Comments similar to the Linux case, 1) above, except that on Solaris
the 1.4 JVM detects the occurrence of signal chaining it doesn't like,
and insists the java option "-Xusealtsigs" be set. This is configured
automatically into the mpiJava 1.2.5 `prunjava' script.
SEE ALSO the notes on thread safety issues, below.
(Note: on Solaris mpiJava has been tested assuming MPICH is built
with cc.)
7) SunOS 5.8 + Sun SDK 1.4.1 + LAM 6.5.6
Comments similar to the Linux MPICH case, 1). No known problems.
SEE ALSO the notes on thread safety issues, below.
8) AIX 3.4 + IBM JDK 1.3.0 Java + IBM MPI (SP2/3)
The JVM sometimes deliberately throws and catches SIGTRAP signals
(in a pattern similar to SIGSEGV, etc with Hotspot?), and the SP2
MPI apparently overrides the JVM handler. We know of no `libjsig'
analogue for this platform, but we found empirically that restoring
the original JVM signal handler for SIGTRAP after the
`System.loadLibrary(mpijava)' call eliminated problems in all our
test cases. This solution is automatically configured into mpiJava
1.2.5.
9) AIX 3.4 + IBM JDK 1.3.0 Java + MPICH 1.2.5
Certain test cases have been observed to intermittently hang on this
platform for unknown reasons. It's use is not recommended.
SEE ALSO the notes on thread safety issues, below.
(Note: on AIX the mpiJava configure script assumes MPICH is built
with cc, not GNU C.)
Issues of Thread Safety (mpiJava 1.2.5)
---------------------------------------
Most MPI implementations are not "thread-safe", and of course Java
uses threads in an essential way---even a single-threaded user program
will have system daemon threads running in the background.
In principle this could be a serious issue for mpiJava. To make
progress we have mainly disregarded the problem, and worked on the
optimistic assumption that provided *MPI* CALLS ARE NEVER MADE
CONCURRENTLY (and, by the way, it is *your* responsibility as the mpiJava
programmer to ensure this!) interference between Java threads should
not cause problems.
A priori this is not guaranteed. The native MPI implementation might
be making OS system calls to send messages over sockets. Daemon
threads or other user threads could also (through the standard Java
API) be concurrently making system calls (e.g. an AWT program could be
communicating with an X server). If the MPI implementation happens not
to invoke its system calls in a thread-safe way, there could still be
interference effects with the system calls invoked internally by the
other "pure Java" threads. (One example is that the MPICH
implementation relies on the `errno' variable; in principle this
could be modified by other threads.)
We have not encountered problems that were *provably* attributable to
this kind of effect. But we *have* encountered problems with graphics
codes (e.g. `examples/Nozzle', `example/potts') running on the Solaris
+ MPICH, Solaris + LAM and AIX + MPICH platforms that look suspiciously
like this. With the default build of MPICH and LAM, these programs
usually fail on these platforms.
Experimentally we found that on Solaris these problems could be eliminated by
reconfiguring MPICH to compile with the flag `-D_REENTRANT':
./configure ... -cflags=-D_REENTRANT
and similarly configuring LAM as follows:
./configure ... --with-cflags=-D_REENTRANT
(Note well these are the `configure' scripts for MPICH and LAM,
*not* mpiJava!)
On AIX the corresponding recipe that worked was:
./configure ... -cflags=-D_THREAD_SAFE
(Note well this is for the `configure' scripts for MPICH, not mpiJava!
Unfortunately we failed to install LAM on AIX. As noted above AIX
+ MPICH has other problems, which are unresolved.)
We were unable to trace the detailed cause of the observed failures, so
it is not 100% certain whether this is really a thread safety issue.
But in general setting `-D_REENTRANT' on Solaris or `-D_THREAD_SAFE'
on AIX would be expected to improve the thread safety characteristics
of C code.
Another change in this release related to thread safety is in the
implementation of the `finalize()' methods of the `Datatype', `Group',
`Op' and `Status' classes. In earlier releases of mpiJava these were
native methods that directly called the corresponding `MPI_Free'
functions. Although this wasn't observed to cause problems, in principle
it is not thread safe because the `finalize()' methods may be called in
a separate garbage collector thread. In the current release the calls
to the native methods are deferred, and invoked in the user thread when
the next MPI operation is explicitly called.
JVMs and "pinning" (mpiJava 1.2.3)
----------------------------------
The garbage collectors associated with early JVMs, such as the
"classic" JVM, supported pinning of Java arrays---fixing the arrays
to a specific physical location while a JNI call was in progress.
Several more modern JVMs (e.g. Hotspot and others) do not support
pinning. Instead JNI calls access elements of Java arrays by first obtaining
a C copy of the Java array. The elements are typically copied back
from the C array to the Java array when the JNI call returns.
mpiJava 1.2.3 supports two approaches to message buffers, reflecting
these two JNI mechanisms---pinning or copying. If you are using a
JVM which is known to support pinning, you may wish to uncomment the
definition of the macro `GC_DOES_PINNING' in the file `src/C/mpiJava.h'.
If this macro is left undefined---presumably meaning the garbage
collector does *not* support pinning---mpiJava will copy buffers
from and to Java arrays explicitly using `MPI_Pack' and `MPI_Unpack'.
This works well with MPICH.
Unfortunately this strategy doesn't always work with IBM MPI,
due to an apparent difference in the semantics of `MPI_Unpack'.
Luckily it turns out that many installations of Java on AIX still use
a variant of the classic JVM, which *does* support pinning. So on AIX
it is probably safest to define the `GC_DOES_PINNING' macro.
[Note added: the `configure' script now attempts to determine whether
the JVM supports pinning and will define the `GC_DOES_PINNING' macro in
make files, if it thinks it does.]
Revision History
----------------
Significant changes from version 1.2.4:
1) Fixes various problems associated with signal handlers
(see discussion above).
2) README file greatly extended to better document supported platforms and
portability issues.
3) Fixes a bug related to the behavior of `MPI_Unpack' on certain
MPI platforms.
4) Fixed some programming errors in the `examples/potts' and
`examples/metropolis' codes.
5) No longer use custom `jvmlauncher' for SunHPC. Instead use
LD_PRELOAD to preload -lmpi library into standard `java' command.
6) Moves freeing of native MPI objects out of the garbage collector
thread, into MPI user thread (no particular problems were observed
with the old strategy, but in principle it isn't thread-unsafe).
Significant changes from version 1.2.3:
1) Supports SunHPC version 4.0. Executable `src/bin/jvmlauncher' added.
Significant changes from version 1.2.2:
1) Supports AIX + POE platform.
Significant changes from version 1.2.1:
1) Major reorganization in handling communication buffers, the better to
support current JVMs, whose garbage collectors often don't implement
pinning.
2) Fix related bug in `Sendrecv', afflicting the `Life.java' example.
3) Fix bug reported by Jatinder Singh when `MPI.ANY_SOURCE' is used with
and `MPI.OBJECT' datatype.
Significant changes from version 1.2:
1) Mainly bug fixes.
Significant changes from version 1.1:
1) Support for the `MPI.OBJECT' basic type (note that this release
uses default JDK serialization, which can be quite inefficient).
2) Support for Linux platforms.
3) Inclusion of new demo programs.
4) Inclusion of `javadoc' documentation.
5) Other minor changes to the API---see the spec in the `doc' directory.
6) Bug fixes.
Known bugs and omissions
------------------------
1) The subclasses of `MPIException' documented in the mpiJava spec are still
not implemented (and in reality mpiJava methods never throw
exceptions---they generally abort the program in case of error).
2) In general, sanity-checking method arguments is not nearly as thorough
as it should be.
mpiJava Directory Structure
---------------------------
mpiJava/
bin/
This directory contains binaries or installed scripts.
For NT releases, sub-directories contain Win32 Dynamic
Link Libraries (.dll).
WMPI/
For NT releases, contains wmpi.dll created by
compiling the JNI C stubs. The directory where the
DLL resides needs to be added to the PATH
environment variable so that it can be found at
run-time by Java.
mpiJava.dll
doc/
examples/
metropolis/
A Monte Carlo program
Nozzle/
A CFD program, with GUI
PingPong/
A simple benchmark, with C and Java versions
potts/
Another Monte Carlo program, with a GUI
simple/
A "Game of Life" program; a "Hello World" program.
lib/
For UNIX releases this directory contains shared libraries.
Class files are contained in a subdirectory.
classes/
The mpiJava class files live here. This directory
should be added to your CLASSPATH enviroment
variable.
mpiJava.zip
src/
C/
The JNI C stubs for mpiJava. This directory
contains the JNI C wrappers and the header files for
mpiJava. These files are compiled into a shared
(.so in UNIX) or dynamic-load-library (.dll in
Win32) that is loaded at runtime by the JVM
(loadlibary(mpiJava)) when the Java MPI interface is
used.
Java/
The Java interface to MPI. This directory includes
a sub-directory (mpi) holding the Java interface to
MPI. These files need to be compiled using a Java
compiler, such as javac. The resulting class files
are copied into the mpiJava/lib/classes directory.
mpi/
scripts/
Various scripts for configuraing and testing mpiJava
under UNIX.
wmpi_jni/
See notes in `NT_INSTALL.TXT'
release/
bin/
The `jvmlauncher' program
tests/
ccl/
comm/
dtyp/
env/
group/
pt2pt/
topo/
References
==========
MPI Home Page:
http://www.mcs.anl.gov/mpi/index.html
MPICH home page:
http://www.mcs.anl.gov/mpi/mpich
LAM home page:
http://www.lam-mpi.org/
WMPI (an MPI for Windows NT):
http://dsg.dei.uc.pt/w32mpi/
Sun J2SE 1.4 download:
http://java.sun.com/j2se/1.4/download.html
IBM Java Developer Kit for Linux:
http://www.ibm.com/java/jdk/download
Contributions
-------------
From Hiromitsu Takagi:
I'd like to inform you that we have successfully built and run it on
Digital UNIX V4.0D (OSF JDK1.1.6) / MPICH but a few modifications are
required.
o add "-I$(JDK)/include/java -I$(JDK)/include/java/alpha" into
INCLUDE of mpiJava-1.1/src/C/Makefile
(jni.h is placed on $(JDK)/include/java/ and jni_md.h is placed on
$(JDK)/include/alpha/.)
o set LDFLAG of mpiJava-1.1/src/C/Makefile "-shared"
[...]
--
Hiromitsu Takagi
Computer Science Division, Electrotechnical Laboratory
Sep 1, 98
---=+ O +=---
Thanks to Rutger Hofman who pointed out a bug in `Request.Waitany',
`Request.Testany' and gave corrections.
Feb 28, 01
---=+ O +=---
The test case in `tests/signals/' is adapted from a bug
report submitted by Sivakumar Venkata Pabolu.
Jan 10, 03