- •Contents
- •List of Figures
- •List of Tables
- •Acknowledgments
- •Introduction to MPI
- •Overview and Goals
- •Background of MPI-1.0
- •Background of MPI-1.1, MPI-1.2, and MPI-2.0
- •Background of MPI-1.3 and MPI-2.1
- •Background of MPI-2.2
- •Who Should Use This Standard?
- •What Platforms Are Targets For Implementation?
- •What Is Included In The Standard?
- •What Is Not Included In The Standard?
- •Organization of this Document
- •MPI Terms and Conventions
- •Document Notation
- •Naming Conventions
- •Semantic Terms
- •Data Types
- •Opaque Objects
- •Array Arguments
- •State
- •Named Constants
- •Choice
- •Addresses
- •Language Binding
- •Deprecated Names and Functions
- •Fortran Binding Issues
- •C Binding Issues
- •C++ Binding Issues
- •Functions and Macros
- •Processes
- •Error Handling
- •Implementation Issues
- •Independence of Basic Runtime Routines
- •Interaction with Signals
- •Examples
- •Point-to-Point Communication
- •Introduction
- •Blocking Send and Receive Operations
- •Blocking Send
- •Message Data
- •Message Envelope
- •Blocking Receive
- •Return Status
- •Passing MPI_STATUS_IGNORE for Status
- •Data Type Matching and Data Conversion
- •Type Matching Rules
- •Type MPI_CHARACTER
- •Data Conversion
- •Communication Modes
- •Semantics of Point-to-Point Communication
- •Buffer Allocation and Usage
- •Nonblocking Communication
- •Communication Request Objects
- •Communication Initiation
- •Communication Completion
- •Semantics of Nonblocking Communications
- •Multiple Completions
- •Non-destructive Test of status
- •Probe and Cancel
- •Persistent Communication Requests
- •Send-Receive
- •Null Processes
- •Datatypes
- •Derived Datatypes
- •Type Constructors with Explicit Addresses
- •Datatype Constructors
- •Subarray Datatype Constructor
- •Distributed Array Datatype Constructor
- •Address and Size Functions
- •Lower-Bound and Upper-Bound Markers
- •Extent and Bounds of Datatypes
- •True Extent of Datatypes
- •Commit and Free
- •Duplicating a Datatype
- •Use of General Datatypes in Communication
- •Correct Use of Addresses
- •Decoding a Datatype
- •Examples
- •Pack and Unpack
- •Canonical MPI_PACK and MPI_UNPACK
- •Collective Communication
- •Introduction and Overview
- •Communicator Argument
- •Applying Collective Operations to Intercommunicators
- •Barrier Synchronization
- •Broadcast
- •Example using MPI_BCAST
- •Gather
- •Examples using MPI_GATHER, MPI_GATHERV
- •Scatter
- •Examples using MPI_SCATTER, MPI_SCATTERV
- •Example using MPI_ALLGATHER
- •All-to-All Scatter/Gather
- •Global Reduction Operations
- •Reduce
- •Signed Characters and Reductions
- •MINLOC and MAXLOC
- •All-Reduce
- •Process-local reduction
- •Reduce-Scatter
- •MPI_REDUCE_SCATTER_BLOCK
- •MPI_REDUCE_SCATTER
- •Scan
- •Inclusive Scan
- •Exclusive Scan
- •Example using MPI_SCAN
- •Correctness
- •Introduction
- •Features Needed to Support Libraries
- •MPI's Support for Libraries
- •Basic Concepts
- •Groups
- •Contexts
- •Intra-Communicators
- •Group Management
- •Group Accessors
- •Group Constructors
- •Group Destructors
- •Communicator Management
- •Communicator Accessors
- •Communicator Constructors
- •Communicator Destructors
- •Motivating Examples
- •Current Practice #1
- •Current Practice #2
- •(Approximate) Current Practice #3
- •Example #4
- •Library Example #1
- •Library Example #2
- •Inter-Communication
- •Inter-communicator Accessors
- •Inter-communicator Operations
- •Inter-Communication Examples
- •Caching
- •Functionality
- •Communicators
- •Windows
- •Datatypes
- •Error Class for Invalid Keyval
- •Attributes Example
- •Naming Objects
- •Formalizing the Loosely Synchronous Model
- •Basic Statements
- •Models of Execution
- •Static communicator allocation
- •Dynamic communicator allocation
- •The General case
- •Process Topologies
- •Introduction
- •Virtual Topologies
- •Embedding in MPI
- •Overview of the Functions
- •Topology Constructors
- •Cartesian Constructor
- •Cartesian Convenience Function: MPI_DIMS_CREATE
- •General (Graph) Constructor
- •Distributed (Graph) Constructor
- •Topology Inquiry Functions
- •Cartesian Shift Coordinates
- •Partitioning of Cartesian structures
- •Low-Level Topology Functions
- •An Application Example
- •MPI Environmental Management
- •Implementation Information
- •Version Inquiries
- •Environmental Inquiries
- •Tag Values
- •Host Rank
- •IO Rank
- •Clock Synchronization
- •Memory Allocation
- •Error Handling
- •Error Handlers for Communicators
- •Error Handlers for Windows
- •Error Handlers for Files
- •Freeing Errorhandlers and Retrieving Error Strings
- •Error Codes and Classes
- •Error Classes, Error Codes, and Error Handlers
- •Timers and Synchronization
- •Startup
- •Allowing User Functions at Process Termination
- •Determining Whether MPI Has Finished
- •Portable MPI Process Startup
- •The Info Object
- •Process Creation and Management
- •Introduction
- •The Dynamic Process Model
- •Starting Processes
- •The Runtime Environment
- •Process Manager Interface
- •Processes in MPI
- •Starting Processes and Establishing Communication
- •Reserved Keys
- •Spawn Example
- •Manager-worker Example, Using MPI_COMM_SPAWN.
- •Establishing Communication
- •Names, Addresses, Ports, and All That
- •Server Routines
- •Client Routines
- •Name Publishing
- •Reserved Key Values
- •Client/Server Examples
- •Ocean/Atmosphere - Relies on Name Publishing
- •Simple Client-Server Example.
- •Other Functionality
- •Universe Size
- •Singleton MPI_INIT
- •MPI_APPNUM
- •Releasing Connections
- •Another Way to Establish MPI Communication
- •One-Sided Communications
- •Introduction
- •Initialization
- •Window Creation
- •Window Attributes
- •Communication Calls
- •Examples
- •Accumulate Functions
- •Synchronization Calls
- •Fence
- •General Active Target Synchronization
- •Lock
- •Assertions
- •Examples
- •Error Handling
- •Error Handlers
- •Error Classes
- •Semantics and Correctness
- •Atomicity
- •Progress
- •Registers and Compiler Optimizations
- •External Interfaces
- •Introduction
- •Generalized Requests
- •Examples
- •Associating Information with Status
- •MPI and Threads
- •General
- •Initialization
- •Introduction
- •File Manipulation
- •Opening a File
- •Closing a File
- •Deleting a File
- •Resizing a File
- •Preallocating Space for a File
- •Querying the Size of a File
- •Querying File Parameters
- •File Info
- •Reserved File Hints
- •File Views
- •Data Access
- •Data Access Routines
- •Positioning
- •Synchronism
- •Coordination
- •Data Access Conventions
- •Data Access with Individual File Pointers
- •Data Access with Shared File Pointers
- •Noncollective Operations
- •Collective Operations
- •Seek
- •Split Collective Data Access Routines
- •File Interoperability
- •Datatypes for File Interoperability
- •Extent Callback
- •Datarep Conversion Functions
- •Matching Data Representations
- •Consistency and Semantics
- •File Consistency
- •Random Access vs. Sequential Files
- •Progress
- •Collective File Operations
- •Type Matching
- •Logical vs. Physical File Layout
- •File Size
- •Examples
- •Asynchronous I/O
- •I/O Error Handling
- •I/O Error Classes
- •Examples
- •Subarray Filetype Constructor
- •Requirements
- •Discussion
- •Logic of the Design
- •Examples
- •MPI Library Implementation
- •Systems with Weak Symbols
- •Systems Without Weak Symbols
- •Complications
- •Multiple Counting
- •Linker Oddities
- •Multiple Levels of Interception
- •Deprecated Functions
- •Deprecated since MPI-2.0
- •Deprecated since MPI-2.2
- •Language Bindings
- •Overview
- •Design
- •C++ Classes for MPI
- •Class Member Functions for MPI
- •Semantics
- •C++ Datatypes
- •Communicators
- •Exceptions
- •Mixed-Language Operability
- •Problems With Fortran Bindings for MPI
- •Problems Due to Strong Typing
- •Problems Due to Data Copying and Sequence Association
- •Special Constants
- •Fortran 90 Derived Types
- •A Problem with Register Optimization
- •Basic Fortran Support
- •Extended Fortran Support
- •The mpi Module
- •No Type Mismatch Problems for Subroutines with Choice Arguments
- •Additional Support for Fortran Numeric Intrinsic Types
- •Language Interoperability
- •Introduction
- •Assumptions
- •Initialization
- •Transfer of Handles
- •Status
- •MPI Opaque Objects
- •Datatypes
- •Callback Functions
- •Error Handlers
- •Reduce Operations
- •Addresses
- •Attributes
- •Extra State
- •Constants
- •Interlanguage Communication
- •Language Bindings Summary
- •Groups, Contexts, Communicators, and Caching Fortran Bindings
- •External Interfaces C++ Bindings
- •Change-Log
- •Bibliography
- •Examples Index
- •MPI Declarations Index
- •MPI Function Index
Chapter 15
Deprecated Functions
15.1 Deprecated since MPI-2.0
The following function is deprecated and is superseded by MPI_TYPE_CREATE_HVECTOR in MPI-2.0. The language independent de nition and the C binding of the deprecated function is the same as of the new function, except of the function name. Only the Fortran language binding is di erent.
MPI_TYPE_HVECTOR( count, blocklength, stride, oldtype, newtype)
IN |
count |
number of blocks (non-negative integer) |
IN |
blocklength |
number of elements in each block (non-negative inte- |
|
|
ger) |
IN |
stride |
number of bytes between start of each block (integer) |
IN |
oldtype |
old datatype (handle) |
OUT |
newtype |
new datatype (handle) |
int MPI_Type_hvector(int count, int blocklength, MPI_Aint stride, MPI_Datatype oldtype, MPI_Datatype *newtype)
MPI_TYPE_HVECTOR(COUNT, BLOCKLENGTH, STRIDE, OLDTYPE, NEWTYPE, IERROR) INTEGER COUNT, BLOCKLENGTH, STRIDE, OLDTYPE, NEWTYPE, IERROR
The following function is deprecated and is superseded by MPI_TYPE_CREATE_HINDEXED in MPI-2.0. The language independent de nition and the C binding of the deprecated function is the same as of the new function, except of the function name. Only the Fortran language binding is di erent.
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
459
460 |
CHAPTER 15. DEPRECATED FUNCTIONS |
1MPI_TYPE_HINDEXED( count, array_of_blocklengths, array_of_displacements, oldtype, new-
2type)
3 |
IN |
count |
number of blocks { also number of entries in |
|
4 |
||||
|
|
array_of_displacements and array_of_blocklengths (non- |
||
5 |
|
|
||
|
|
negative integer) |
||
6 |
|
|
||
|
|
|
||
7 |
IN |
array_of_blocklengths |
number of elements in each block (array of non-negative |
|
8 |
|
|
integers) |
|
9 |
IN |
array_of_displacements |
byte displacement of each block (array of integer) |
|
|
||||
10 |
IN |
oldtype |
old datatype (handle) |
|
11 |
||||
|
|
|
||
12 |
OUT |
newtype |
new datatype (handle) |
|
13 |
|
|
|
22The following function is deprecated and is superseded by
23MPI_TYPE_CREATE_STRUCT in MPI-2.0. The language independent de nition and the C
24binding of the deprecated function is the same as of the new function, except of the function
25name. Only the Fortran language binding is di erent.
26
27
28MPI_TYPE_STRUCT(count, array_of_blocklengths, array_of_displacements, array_of_types,
29newtype)
30
31
32
33
34
35
IN |
count |
number of blocks (integer) (non-negative integer) { |
|
|
also number of entries in arrays array_of_types, |
|
|
array_of_displacements and array_of_blocklengths |
IN |
array_of_blocklength |
number of elements in each block (array of non-negative |
|
|
integer) |
36
37
38
39
40
41
IN |
array_of_displacements |
byte displacement of each block (array of integer) |
IN |
array_of_types |
type of elements in each block (array of handles to |
|
|
datatype objects) |
OUT |
newtype |
new datatype (handle) |
42 |
int MPI_Type_struct(int count, int *array_of_blocklengths, |
|
MPI_Aint *array_of_displacements, |
||
43 |
||
MPI_Datatype *array_of_types, MPI_Datatype *newtype) |
||
44 |
||
|
||
45 |
MPI_TYPE_STRUCT(COUNT, ARRAY_OF_BLOCKLENGTHS, ARRAY_OF_DISPLACEMENTS, |
|
|
||
46 |
ARRAY_OF_TYPES, NEWTYPE, IERROR) |
|
|
47INTEGER COUNT, ARRAY_OF_BLOCKLENGTHS(*), ARRAY_OF_DISPLACEMENTS(*),
48ARRAY_OF_TYPES(*), NEWTYPE, IERROR
15.1. DEPRECATED SINCE MPI-2.0 |
461 |
The following function is deprecated and is superseded by MPI_GET_ADDRESS in MPI- 2.0. The language independent de nition and the C binding of the deprecated function is the same as of the new function, except of the function name. Only the Fortran language binding is di erent.
MPI_ADDRESS(location, address)
IN |
location |
location in caller memory (choice) |
OUT |
address |
address of location (integer) |
int MPI_Address(void* location, MPI_Aint *address)
MPI_ADDRESS(LOCATION, ADDRESS, IERROR) <type> LOCATION(*)
INTEGER ADDRESS, IERROR
The following functions are deprecated and are superseded by
MPI_TYPE_GET_EXTENT in MPI-2.0.
MPI_TYPE_EXTENT(datatype, extent)
IN |
datatype |
datatype (handle) |
OUT |
extent |
datatype extent (integer) |
int MPI_Type_extent(MPI_Datatype datatype, MPI_Aint *extent)
MPI_TYPE_EXTENT(DATATYPE, EXTENT, IERROR)
INTEGER DATATYPE, EXTENT, IERROR
Returns the extent of a datatype, where extent is as de ned on page 96.
The two functions below can be used for nding the lower bound and the upper bound of a datatype.
MPI_TYPE_LB( datatype, displacement)
IN |
datatype |
datatype (handle) |
OUT |
displacement |
displacement of lower bound from origin, in bytes (in- |
|
|
teger) |
int MPI_Type_lb(MPI_Datatype datatype, MPI_Aint* displacement)
MPI_TYPE_LB( DATATYPE, DISPLACEMENT, IERROR)
INTEGER DATATYPE, DISPLACEMENT, IERROR
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
1
2
3
4
5
6
462 |
CHAPTER 15. DEPRECATED FUNCTIONS |
MPI_TYPE_UB( datatype, displacement)
IN |
datatype |
datatype (handle) |
OUT |
displacement |
displacement of upper bound from origin, in bytes (in- |
|
|
teger) |
7int MPI_Type_ub(MPI_Datatype datatype, MPI_Aint* displacement)
8
MPI_TYPE_UB( DATATYPE, DISPLACEMENT, IERROR)
9
INTEGER DATATYPE, DISPLACEMENT, IERROR
10
11The following function is deprecated and is superseded by
12MPI_COMM_CREATE_KEYVAL in MPI-2.0. The language independent de nition of the
13deprecated function is the same as that of the new function, except for the function name
14and a di erent behavior in the C/Fortran language interoperability, see Section 16.3.7 on
15page 505. The language bindings are modi ed.
16 |
|
|
|
|
17 |
|
|
|
|
18 |
MPI_KEYVAL_CREATE(copy_fn, delete_fn, keyval, extra_state) |
|||
19 |
IN |
copy_fn |
Copy callback function for keyval |
|
|
||||
20 |
IN |
delete_fn |
Delete callback function for keyval |
|
21 |
||||
|
|
|
||
22 |
OUT |
keyval |
key value for future access (integer) |
|
23 |
IN |
extra_state |
Extra state for callback functions |
|
|
||||
24
25
int MPI_Keyval_create(MPI_Copy_function *copy_fn, MPI_Delete_function
26
*delete_fn, int *keyval, void* extra_state)
27
28MPI_KEYVAL_CREATE(COPY_FN, DELETE_FN, KEYVAL, EXTRA_STATE, IERROR)
29EXTERNAL COPY_FN, DELETE_FN
30INTEGER KEYVAL, EXTRA_STATE, IERROR
31 |
The copy_fn function is invoked when a communicator is duplicated by |
|
32 |
||
MPI_COMM_DUP. copy_fn should be of type MPI_Copy_function, which is de ned as follows: |
||
33 |
||
|
||
34 |
|
|
35 |
typedef int MPI_Copy_function(MPI_Comm oldcomm, int keyval, |
|
|
||
36 |
void *extra_state, void *attribute_val_in, |
|
|
||
37 |
void *attribute_val_out, int *flag) |
|
|
38
39A Fortran declaration for such a function is as follows:
40SUBROUTINE COPY_FUNCTION(OLDCOMM, KEYVAL, EXTRA_STATE, ATTRIBUTE_VAL_IN,
41 |
ATTRIBUTE_VAL_OUT, FLAG, IERR) |
42INTEGER OLDCOMM, KEYVAL, EXTRA_STATE, ATTRIBUTE_VAL_IN,
43ATTRIBUTE_VAL_OUT, IERR
44LOGICAL FLAG
45copy_fn may be speci ed as MPI_NULL_COPY_FN or MPI_DUP_FN from either C or
46FORTRAN; MPI_NULL_COPY_FN is a function that does nothing other than returning
47ag = 0 and MPI_SUCCESS. MPI_DUP_FN is a simple-minded copy function that sets ag =
48
15.1. DEPRECATED SINCE MPI-2.0 |
463 |
1, returns the value of attribute_val_in in attribute_val_out, and returns MPI_SUCCESS. Note that MPI_NULL_COPY_FN and MPI_DUP_FN are also deprecated.
Analogous to copy_fn is a callback deletion function, de ned as follows. The delete_fn function is invoked when a communicator is deleted by MPI_COMM_FREE or when a call is made explicitly to MPI_ATTR_DELETE. delete_fn should be of type MPI_Delete_function, which is de ned as follows:
typedef int MPI_Delete_function(MPI_Comm comm, int keyval, void *attribute_val, void *extra_state);
A Fortran declaration for such a function is as follows:
SUBROUTINE DELETE_FUNCTION(COMM, KEYVAL, ATTRIBUTE_VAL, EXTRA_STATE, IERR) INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, EXTRA_STATE, IERR
delete_fn may be speci ed as MPI_NULL_DELETE_FN from either C or FORTRAN; MPI_NULL_DELETE_FN is a function that does nothing, other than returning MPI_SUCCESS. Note that MPI_NULL_DELETE_FN is also deprecated.
The following function is deprecated and is superseded by MPI_COMM_FREE_KEYVAL in MPI-2.0. The language independent de nition of the deprecated function is the same as of the new function, except of the function name. The language bindings are modi ed.
MPI_KEYVAL_FREE(keyval)
INOUT keyval |
Frees the integer key value (integer) |
int MPI_Keyval_free(int *keyval)
MPI_KEYVAL_FREE(KEYVAL, IERROR)
INTEGER KEYVAL, IERROR
The following function is deprecated and is superseded by MPI_COMM_SET_ATTR in MPI-2.0. The language independent de nition of the deprecated function is the same as of the new function, except of the function name. The language bindings are modi ed.
MPI_ATTR_PUT(comm, keyval, attribute_val)
INOUT comm communicator to which attribute will be attached (handle)
IN |
keyval |
key value, as returned by |
|
|
MPI_KEYVAL_CREATE (integer) |
IN |
attribute_val |
attribute value |
int MPI_Attr_put(MPI_Comm comm, int keyval, void* attribute_val)
MPI_ATTR_PUT(COMM, KEYVAL, ATTRIBUTE_VAL, IERROR)
INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
The following function is deprecated and is superseded by MPI_COMM_GET_ATTR in MPI-2.0. The language independent de nition of the deprecated function is the same as of the new function, except of the function name. The language bindings are modi ed.
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
464 |
CHAPTER 15. DEPRECATED FUNCTIONS |
1
2
3
MPI_ATTR_GET(comm, keyval, attribute_val, ag)
IN |
comm |
communicator to which attribute is attached (handle) |
4
5
6
7
8
9
IN |
keyval |
key value (integer) |
OUT |
attribute_val |
attribute value, unless ag = false |
OUT |
ag |
true if an attribute value was extracted; false if no |
|
|
attribute is associated with the key |
10int MPI_Attr_get(MPI_Comm comm, int keyval, void *attribute_val, int *flag)
11MPI_ATTR_GET(COMM, KEYVAL, ATTRIBUTE_VAL, FLAG, IERROR)
12INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
13LOGICAL FLAG
14
15The following function is deprecated and is superseded by MPI_COMM_DELETE_ATTR
16in MPI-2.0. The language independent de nition of the deprecated function is the same as
17of the new function, except of the function name. The language bindings are modi ed.
18 |
|
|
|
|
19 |
MPI_ATTR_DELETE(comm, keyval) |
|||
20 |
||||
|
|
|
||
21 |
INOUT |
comm |
communicator to which attribute is attached (handle) |
|
22 |
IN |
keyval |
The key value of the deleted attribute (integer) |
|
|
|
|
||
23 |
|
|
|
|
24 |
int MPI_Attr_delete(MPI_Comm comm, int keyval) |
|||
|
||||
25 |
|
|
|
|
26 |
MPI_ATTR_DELETE(COMM, KEYVAL, IERROR) |
|||
27 |
INTEGER COMM, KEYVAL, IERROR |
|||
28 |
The |
following |
function is deprecated and is superseded by |
|
29 |
||||
MPI_COMM_CREATE_ERRHANDLER in MPI-2.0. The language independent de nition |
||||
|
||||
30 |
of the deprecated function is the same as of the new function, except of the function name. |
|
31 |
||
The language bindings are modi ed. |
||
32 |
||
|
||
33 |
|
|
34 |
MPI_ERRHANDLER_CREATE( function, errhandler ) |
|
|
35
36
37
38
IN |
function |
user de ned error handling procedure |
OUT |
errhandler |
MPI error handler (handle) |
39 |
int MPI_Errhandler_create(MPI_Handler_function *function, |
40 |
MPI_Errhandler *errhandler) |
41
MPI_ERRHANDLER_CREATE(FUNCTION, ERRHANDLER, IERROR)
42
EXTERNAL FUNCTION
43
INTEGER ERRHANDLER, IERROR
44
45Register the user routine function for use as an MPI exception handler. Returns in
46errhandler a handle to the registered exception handler.
47In the C language, the user routine should be a C function of type MPI_Handler_function,
48which is de ned as: