- •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 12
External Interfaces
12.1 Introduction
This chapter begins with calls used to create generalized requests, which allow users to create new nonblocking operations with an interface similar to what is present in MPI. This can be used to layer new functionality on top of MPI. Next, Section 12.3 deals with setting the information found in status. This is needed for generalized requests.
The chapter continues, in Section 12.4, with a discussion of how threads are to be handled in MPI. Although thread compliance is not required, the standard speci es how threads are to work if they are provided.
12.2 Generalized Requests
The goal of generalized requests is to allow users to de ne new nonblocking operations. Such an outstanding nonblocking operation is represented by a (generalized) request. A fundamental property of nonblocking operations is that progress toward the completion of this operation occurs asynchronously, i.e., concurrently with normal program execution. Typically, this requires execution of code concurrently with the execution of the user code, e.g., in a separate thread or in a signal handler. Operating systems provide a variety of mechanisms in support of concurrent execution. MPI does not attempt to standardize or replace these mechanisms: it is assumed programmers who wish to de ne new asynchronous operations will use the mechanisms provided by the underlying operating system. Thus, the calls in this section only provide a means for de ning the e ect of MPI calls such as MPI_WAIT or MPI_CANCEL when they apply to generalized requests, and for signaling to MPI the completion of a generalized operation.
Rationale. It is tempting to also de ne an MPI standard mechanism for achieving concurrent execution of user-de ned nonblocking operations. However, it is very dif-cult to de ne such a mechanism without consideration of the speci c mechanisms used in the operating system. The Forum feels that concurrency mechanisms are a proper part of the underlying operating system and should not be standardized by MPI; the MPI standard should only deal with the interaction of such mechanisms with
MPI. (End of rationale.)
For a regular request, the operation associated with the request is performed by the MPI implementation, and the operation completes without intervention by the application.
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
373
374 |
CHAPTER 12. EXTERNAL INTERFACES |
1For a generalized request, the operation associated with the request is performed by the
2application; therefore, the application must notify MPI when the operation completes. This
3is done by making a call to MPI_GREQUEST_COMPLETE. MPI maintains the \completion"
4status of generalized requests. Any other request state has to be maintained by the user.
5
6
7
A new generalized request is started with
8MPI_GREQUEST_START(query_fn, free_fn, cancel_fn, extra_state, request)
9
10
11
12
13
14
15
16
17
18
19
IN |
query_fn |
callback function invoked when request status is queried |
|
|
(function) |
IN |
free_fn |
callback function invoked when request is freed (func- |
|
|
tion) |
IN |
cancel_fn |
callback function invoked when request is cancelled |
|
|
(function) |
IN |
extra_state |
extra state |
OUT |
request |
generalized request (handle) |
20 int MPI_Grequest_start(MPI_Grequest_query_function *query_fn, MPI_Grequest_free_function *free_fn, MPI_Grequest_cancel_function *cancel_fn, void *extra_state, MPI_Request *request)
MPI_GREQUEST_START(QUERY_FN, FREE_FN, CANCEL_FN, EXTRA_STATE, REQUEST, IERROR)
26INTEGER REQUEST, IERROR
27EXTERNAL QUERY_FN, FREE_FN, CANCEL_FN
28INTEGER (KIND=MPI_ADDRESS_KIND) EXTRA_STATE
29 |
fstatic MPI::Grequest |
30 |
|
31 |
MPI::Grequest::Start(const MPI::Grequest::Query_function* |
32 |
query_fn, const MPI::Grequest::Free_function* free_fn, |
33 |
const MPI::Grequest::Cancel_function* cancel_fn, |
34 |
void *extra_state) (binding deprecated, see Section 15.2) g |
35 |
|
36Advice to users. Note that a generalized request belongs, in C++, to the class
37MPI::Grequest, which is a derived class of MPI::Request. It is of the same type as
38regular requests, in C and Fortran. (End of advice to users.)
39
40The call starts a generalized request and returns a handle to it in request.
41The syntax and meaning of the callback functions are listed below. All callback func-
42tions are passed the extra_state argument that was associated with the request by the
43starting call MPI_GREQUEST_START. This can be used to maintain user-de ned state for
44the request.
45In C, the query function is
46
typedef int MPI_Grequest_query_function(void *extra_state,
47
MPI_Status *status);
48
12.2. GENERALIZED REQUESTS |
375 |
in Fortran
SUBROUTINE GREQUEST_QUERY_FUNCTION(EXTRA_STATE, STATUS, IERROR) INTEGER STATUS(MPI_STATUS_SIZE), IERROR INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
and in C++
ftypedef int MPI::Grequest::Query_function(void* extra_state, MPI::Status& status); (binding deprecated, see Section 15.2) g
query_fn function computes the status that should be returned for the generalized request. The status also includes information about successful/unsuccessful cancellation of the request (result to be returned by MPI_TEST_CANCELLED).
query_fn callback is invoked by the MPI_fWAITjTESTgfANYjSOMEjALLg call that completed the generalized request associated with this callback. The callback function is also invoked by calls to MPI_REQUEST_GET_STATUS, if the request is complete when the call occurs. In both cases, the callback is passed a reference to the corresponding status variable passed by the user to the MPI call; the status set by the callback function is returned by the MPI call. If the user provided MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE to the MPI function that causes query_fn to be called, then MPI will pass a valid status object to query_fn, and this status will be ignored upon return of the callback function. Note that query_fn is invoked only after MPI_GREQUEST_COMPLETE is called on the request; it may be invoked several times for the same generalized request, e.g., if the user calls MPI_REQUEST_GET_STATUS several times for this request. Note also that a call to MPI_fWAITjTESTgfSOMEjALLg may cause multiple invocations of query_fn callback functions, one for each generalized request that is completed by the MPI call. The order of these invocations is not speci ed by MPI.
In C, the free function is
typedef int MPI_Grequest_free_function(void *extra_state);
and in Fortran
SUBROUTINE GREQUEST_FREE_FUNCTION(EXTRA_STATE, IERROR)
INTEGER IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
and in C++
ftypedef int MPI::Grequest::Free_function(void* extra_state); (binding deprecated, see Section 15.2) g
free_fn function is invoked to clean up user-allocated resources when the generalized request is freed.
free_fn callback is invoked by the MPI_fWAITjTESTgfANYjSOMEjALLg call that completed the generalized request associated with this callback. free_fn is invoked after the call to query_fn for the same request. However, if the MPI call completed multiple generalized requests, the order in which free_fn callback functions are invoked is not speci ed by MPI. free_fn callback is also invoked for generalized requests that are freed by a call to
MPI_REQUEST_FREE (no call to WAIT_fWAITjTESTgfANYjSOMEjALLg will occur for such a request). In this case, the callback function will be called either in the MPI call
MPI_REQUEST_FREE(request), or in the MPI call MPI_GREQUEST_COMPLETE(request),
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
376 |
CHAPTER 12. EXTERNAL INTERFACES |
1whichever happens last, i.e., in this case the actual freeing code is executed as soon as both
2calls MPI_REQUEST_FREE and MPI_GREQUEST_COMPLETE have occurred. The request
3is not deallocated until after free_fn completes. Note that free_fn will be invoked only once
4
5
per request by a correct program.
6Advice to users. Calling MPI_REQUEST_FREE(request) will cause the request handle
7to be set to MPI_REQUEST_NULL. This handle to the generalized request is no longer
8valid. However, user copies of this handle are valid until after free_fn completes since
9MPI does not deallocate the object until then. Since free_fn is not called until after
10MPI_GREQUEST_COMPLETE, the user copy of the handle can be used to make this
11call. Users should note that MPI will deallocate the object after free_fn executes. At
12this point, user copies of the request handle no longer point to a valid request. MPI
13will not set user copies to MPI_REQUEST_NULL in this case, so it is up to the user to
14avoid accessing this stale handle. This is a special case where MPI defers deallocating
15the object until a later time that is known by the user. (End of advice to users.)
16 |
|
17 |
In C, the cancel function is |
|
|
18 |
typedef int MPI_Grequest_cancel_function(void *extra_state, int complete); |
|
|
19 |
|
20 |
in Fortran |
21 |
SUBROUTINE GREQUEST_CANCEL_FUNCTION(EXTRA_STATE, COMPLETE, IERROR) |
|
|
22 |
INTEGER IERROR |
|
|
23 |
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE |
|
|
24 |
LOGICAL COMPLETE |
|
|
25 |
|
26 |
and in C++ |
27 |
ftypedef int MPI::Grequest::Cancel_function(void* extra_state, |
28 |
|
29 |
bool complete); (binding deprecated, see Section 15.2) g |
30cancel_fn function is invoked to start the cancelation of a generalized request. It is
31called by MPI_CANCEL(request). MPI passes to the callback function complete=true if
32MPI_GREQUEST_COMPLETE was already called on the request, and
33complete=false otherwise.
34All callback functions return an error code. The code is passed back and dealt with as
35appropriate for the error code by the MPI function that invoked the callback function. For
36example, if error codes are returned then the error code returned by the callback function
37will be returned by the MPI function that invoked the callback function. In the case of
38an MPI_fWAITjTESTgfANYg call that invokes both query_fn and free_fn, the MPI call will
39return the error code returned by the last callback, namely free_fn. If one or more of the
40requests in a call to MPI_fWAITjTESTgfSOMEjALLg failed, then the MPI call will return
41MPI_ERR_IN_STATUS. In such a case, if the MPI call was passed an array of statuses, then
42MPI will return in each of the statuses that correspond to a completed generalized request
43the error code returned by the corresponding invocation of its free_fn callback function.
44However, if the MPI function was passed MPI_STATUSES_IGNORE, then the individual error
45codes returned by each callback functions will be lost.
46
47Advice to users. query_fn must not set the error eld of status since query_fn may
48be called by MPI_WAIT or MPI_TEST, in which case the error eld of status should