diff --git a/README.JAVA.txt b/README.JAVA.txt index 97d398b3ad..2f93465ee9 100644 --- a/README.JAVA.txt +++ b/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/ +$ ./configure --with-platform=contrib/platform/hadoop/ ... or -./configure --enable-mpi-java --with-jdk-bindir= ---with-jdk-headers=bar ... +$ ./configure --enable-mpi-java --with-jdk-bindir= + --with-jdk-headers= ... 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 java +$ mpirun java 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); ---------------------------------------------------------------------------- diff --git a/ompi/mpi/java/README.txt b/ompi/mpi/java/README.txt deleted file mode 100644 index 4997df07c3..0000000000 --- a/ompi/mpi/java/README.txt +++ /dev/null @@ -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 `/src/scripts' to your path environment - variable. - - Add the directory `/lib/classes' to your CLASSPATH - environment variable. - - Add the directory `/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 java - -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 - -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 java - -(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 - -