File: README

package info (click to toggle)
mpich 1.2.5.3-5
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 53,880 kB
  • ctags: 44,904
  • sloc: ansic: 260,029; cpp: 91,556; sh: 42,421; java: 33,448; makefile: 8,959; fortran: 4,601; tcl: 3,548; f90: 3,517; perl: 2,251; asm: 999; csh: 856
file content (375 lines) | stat: -rw-r--r-- 14,205 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
-*- text -*-

Copyright 1997-2000, University of Notre Dame.
Authors: Jeremy G. Siek, Jeffery M. Squyres, Michael P. McNally, and
         Andrew Lumsdaine

This file is part of the Notre Dame C++ bindings for MPI.

You should have received a copy of the License Agreement for the Notre
Dame C++ bindings for MPI along with the software; see the file
LICENSE.  If not, contact Office of Research, University of Notre
Dame, Notre Dame, IN 46556.

Permission to modify the code and to distribute modified code is
granted, provided the text of this NOTICE is retained, a notice that
the code was modified is included with the above COPYRIGHT NOTICE and
with the COPYRIGHT NOTICE in the LICENSE file, and that the LICENSE
file is distributed with the modified code.

LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.
By way of example, but not limitation, Licensor MAKES NO
REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE COMPONENTS
OR DOCUMENTATION WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS
OR OTHER RIGHTS.

Additional copyrights may follow.

-----------------------------------------------------------------------

                       MPI 1.2 C++ Bindings

I. INTRODUCTION
---------------

This implementation of the MPI 1.2 C++ bindings is not a standalone
C++ MPI implementation; it is a layer on top of the MPI 1.1/1.2 C
bindings for MPI.  You must already have an MPI implementation in
order to use this package.

The MPI standards documents are available from
http://www.mpi-forum.org/.


I.1 DO YOU NEED THIS PACKAGE?
-----------------------------

Several implementations of MPI already include C++ bindings (some
include this package directly, some have their own implementations
originally based on this package).  If you are using any one of the
following implementations of MPI (or later versions), you do not need
this package:

	LAM/MPI 6.3.x/6.4.x
	MPICH 1.2.x
	SGI Message Passing Toolkit 1.4
	Sun HPC Cluster Tools 3.1

Indeed, if you are using one of the above MPI implementations, it is
explicitly *not* supported to use this package in lieu of the C++
bindings included in the implementation.  Consult your MPI
implementation's documentation for more information.

As such, this package is mainly intended for other MPI developers to
include in their implementations; many users will not need to install
it themselves.  If your MPI implementation does not include C++
bindings, you may wish to point the authors in the direction of this
package.


I.2 SUPPORTED SYSTEMS
---------------------

This implementation of the MPI C++ bindings are available from its
main distribution site:

        http://www.mpi.nd.edu/research/mpi2c++/

There are two main factors that determine whether this package will
work for you:

1) The underlying MPI.  As discussed above, you should only be using
this package if you are *not* using an MPI implementation that already
has C++ bindings included.

2) The C++ compiler.  When this package was originally written, C++
support was sketchy at best.  In the two years since original
publication, vendor C++ support has vastly improved.  Most modern C++
compilers include support for the features necessary to compile this
package.  Two notable exceptions of the original supported C++
compilers exist:

        - The HP CC compiler cannot be used; use aCC instead.  This
          also applies to other non-ANSI C++ compilers -- you *must*
          be using an ANSI C++ compiler.
        - Versions of the GNU g++ compiler prior to 2.95.2 are not
          supported.

In general, the more up-to-date your C++ compiler is, the better.  The
main sticky points for C++ compilers are the following:

	- namespace support (Note 1)
	- the "bool" type (Note 2)
	- exception support (Note 2)

Note 1: Some compiler still have sketchy namespace support.  The
configure script in this package will attempt to determine this, and
work around it.  If all else fails, you can manually disable namespace
support and force the workaround code.

Note 2: Support for these features in modern C++ compilers is fairly
universal; you shouldn't encounter a problem with respects to this
issue.


II. USING THE LIBRARY
---------------------

Include files

Users should include <mpi++.h> in order to use the MPI C++ bindings.
This is not conformant with the MPI-2 standard, which says the header
for the C++ bindings should be in <mpi.h>. The name mpi++.h was used
because as a layer on top of existing MPI implementations.  We do not
have access to the underlying <mpi.h>.


Libraries

After following the instructions in the INSTALL file, libmpi++.a (or
libpmpi++.a) will be created.  This library needs to be linked with
all user MPI C++ applications, in addition to any other libraries that
the underlying MPI library requires.  This link step is automatically
handled for the user by the "balky" compiler wrapper script (see
below).


Best Automated Language Kompiler Yet (balky)

balky is a wrapper compiler script that will include all necessary
compiler switches for compiling and linking MPI C++ user programs.
After a successful "make install", it will be installed into
$prefix/bin.  A sample C++ MPI program is shown below, followed by the
balky command to compile it. Note that you do not need to specify
were the <mpi++.h> file is found, as balky automatically takes care
of this.

foo.cc:
-----
#include <iostream.h>
#include <mpi++.h>

int
main(int argc, char* argv[])
{
  MPI::Init(argc, argv);
  int rank = MPI::COMM_WORLD.Get_rank();
  int size = MPI::COMM_WORLD.Get_size();
  cout << "Hello world, I am " << rank << " of " << size << endl;
  MPI::Finalize();
  return 0;
}
-----

Compilation of foo.cc:
-----
unix% balky foo.cc -O -o foo
unix% 
-----


III. IMPLEMENTATION ISSUES
--------------------------

Namespaces

The MPI-2 standard requires that the C++ bindings reside in an MPI
namespace.  As mentioned above, support for namespaces in many modern
C++ compilers is still dubious (GNU g++ being the most obvious
example).  Compilers that fully support namespaces will utilize this
C++ feature when compiling the bindings.  Compilers that do not
implement namespaces will use nested classes instead.

The configure script will attempt to determine if your C++ compiler
supports namespace.  If the configure script decides incorrectly, you
can override the results of the namespace test with command line
switches (see the INSTALL file).


Profiling

The C++ bindings can be configured in two ways: profilable and not
profilable. With the profilable version, it is posible to link in an
intermediate MPI:: layer in order to profile MPI functionality.

The profilable C++ bindings have two layers.  The upper layer consists
of classes and functions in the MPI namespace that can be replaced by
user- or vendor-supplied functions.  The lower layer resides in the
PMPI namespace and does the actual work (usually by just calling the
underlying MPI C bindings).

The non-profilable version of the C++ bindings is a single layer; the
MPI:: classes and functions which call the C bindings.

The non-profilable version is fully inlined so that it adds very
little overhead to the C bindings.  The bottom layer of the profilable
bindings is also fully inlined, so there is only the cost of one extra
function call (from the MPI:: layer to the PMPI:: layer), which is
necessary to allow for profiling.


MPI-2 Bindings Names

Names for MPI-1 functions were not always consistent; some are of the
form MPI_Object_action, while others are of the form
MPI_Object_subset.  Verb usage was not consistent either, such as
MPI_ERRHANDLER_SET and MPI_ATTR_PUT.

The MPI Forum decided to use a completely consistent naming scheme for
MPI-2, and decided that the C++ bindings for MPI-1.2 would follow this
consistent naming scheme.  As such, many of the C++ bindings have
slightly different names than their C and Fortran counterparts.  For
example, MPI_COMM_RANK became MPI::Comm::Get_rank().  A table that
cross references the MPI language neutral names to their C++ bindings
counterparts is provided in Annex B of the MPI-2 standard (see
http://www.mpi-forum.org/).


MPI-2 Deprecated Functions

The MPI Forum decided to deprecate several functions in MPI-1; the use
of these functions is discouraged in future MPI programs.  But since
there is probably some existing code that uses these functions, the
MPI Forum did not remove them from the 1.2 standard.  However, since
the C++ bindings are new, there is no code that will break by the
removal of these functions.  Therefore, the MPI 1.2 C++ function names
do not include bindings for the deprecated functions.

Most of the deprecated names were replaced with new names, some of
which have different semantics than the original name.  The C++
bindings for these functions are included in this library because the
new semantics could be replicated based upon the old MPI-1 C
functions.  Table 2 lists the deprecated MPI-1 names and the
corresponding new C++ names.

MPI 1.1 Function        C++ Binding
======================= =====================================
MPI_ADDRESS             MPI::Get_address
MPI_TYPE_HINDEXED       MPI::Datatype::Create_hindexed
MPI_TYPE_HVECTOR        MPI::Datatype::Create_hvector
MPI_TYPE_STRUCT         MPI::Datatype::Create_struct

MPI_TYPE_EXTENT         MPI::Datatype::Get_extent
MPI_TYPE_UB             MPI::Datatype::Get_extent
MPI_TYPE_LB             MPI::Datatype::Get_extent
MPI_LB                  No corresponding MPI-2 Binding
MPI_UB                  No corresponding MPI-2 Binding
======================= =====================================
           Table 2: Deprecated MPI-1 functions


New MPI 1.2 Functions

There is one new function specified in the standard for MPI 1.2,
MPI_GET_VERSION.  If your underlying MPI has this function, support
for it will be included in this package.


File Organization

The "real" functionality of the C++ bindings can be found in the src/
subdirectory and a bunch of header files in src/mpi2c++ subdirectory
suffixed with "_inln.h".  The functions in these files contain the
calls to the underlying C bindings.  Preprocessor macros "assign"
these functions to either the MPI:: classes or the PMPI:: classes,
depending on whether the profiling option was selected in the
configure step (see the INSTALL file). These files comprise the bottom
layer of the profilable C++ bindings, and the only layer of the
non-profilable bindings.

The upper layer of the profilable bindings consist of the files with
the ".cc" extension.  They contain the functions in the MPI::
namespace.


Implementors: How to Merge <mpi++.h> and <mpi.h>

1. Put extern "C" { } around everything in <mpi.h>
2. Put a preprocesor macro around the extern "C" to ensure that it is
   only used when the preprocessor macro "_cplus_plus" or
   "__cplusplus" is defined.
3. Insert the contents of <mpi++.h> at the end of <mpi.h> (You will
   still need all the other header files that are included in
   <mpi++.h>, but they can be collapsed into one file if necessary).

Figure 1 shows an example of these steps.

----------------------------------------------------------------------
#ifdef _cplus_plus
extern "C" {
#endif

/* The contents of <mpi.h> */

#if defined(_cplus_plus) || defined(__cplusplus)
}

/* The contents of <mpi++.h> */

#endif
----------------------------------------------------------------------
    Figure 1: Example of how to merge <mpi++.h> and <mpi.h>


Miscellanious Implementation Notes

COMM_NULL: The MPI-2 standard does not specify exactly how
MPI::COMM_NULL should be implemented. It only specifies that
MPI::COMM_NULL must be comparible with and assignable to instances of
MPI::Comm's derived classes.  This package implements COMM_NULL as a
singleton object of a class named Comm_Null (which is a base class of
MPI::Comm).

MPI::Status: There are several functions in the C++ bindings with two
versions, one that takes a MPI::Status object and one that does not.
Since the underlying MPI C function always requires an MPI_Status
handle in its parameter list, some value must be used.  In the cases
where there is no MPI::Status object being passed to the C++ function,
if the underlying MPI has the constants MPI_STATUS_IGNORE and
MPI_STATUSES_IGNORE defined, they will be used.  If not, a private
MPI:Status instance such as "ignored_status" is used.  ignored_status
is declared as a static object in each of the MPI classes that need to
use it.  That is, there is only one ignored_status for each type of
MPI class that requires it.

Profiling: When the library is compiled with profiling enabled, the
MPI:: functions only call their corresponding PMPI:: functions.  The
one exception to this rule is the Clone method.  This method currently
performs some actions in the MPI layer before invoking the underlying
PMPI:: Clone function.  It is recomended that users do not attempt to
profile this function.


IV. CONTACT INFORMATION
-----------------------

These MPI C++ bindings are available from their main distribution site:

        http://www.mpi.nd.edu/research/mpi2c++/

This distribution includes:

        - Source code for the MPI 1.2 C++ bindings (src/ subdirectory)
        - Several example programs (contrib/examples/ subdirectory)
        - All the examples from chapter 10 of the MPI-2 standard
          (contrib/examples/chapter_10_mpi2.cc)
        - A test suite for the MPI 1.2 C++ bindings
          (contrib/test_suite/)

See the INSTALL file in this directory for how to build the C++
bindings library.  The INSTALL file also includes information on how
to use the bindings.

Bug reports should be sent to mpi2c++-bugs@mpi.nd.edu.  Please include
the output from configure, make, make install, and the program that
you are having problems with.

Questions, comments, suggestions, and requests for additional
information should be sent to mpi2c++@mpi.nd.edu

A mailing list exists for MPI-2 C++ Bindings announcements regarding
releases, important patches, etc. Users can subscribe to it by sending
a message to majordomo@mpi.nd.edu with the message:

           subscribe mpi2cpp-announce