Examples

314. Examples

Up: Consistency and Semantics Next: Asynchronous I/O Previous: File Size

The examples in this section illustrate the application of the MPI consistency and semantics guarantees. These address

conflicting accesses on file handles obtained from a single collective open, and
all accesses on file handles obtained from two separate collective opens.

The simplest way to achieve consistency for conflicting accesses is to obtain sequential consistency by setting atomic mode. For the code below, process 1 will read either 0 or 10 integers. If the latter, every element of b will be 5. If nonatomic mode is set, the results of the read are undefined.

/* Process 0 */ 
int  i, a[10]; 
int  TRUE = 1; 
 
for ( i=0;i<10;i++) 
   a[i] = 5; 
 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh0 ); 
MPI_File_set_view( fh0, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_set_atomicity( fh0, TRUE ); 
MPI_File_write_at(fh0, 0, a, 10, MPI_INT, &status); 
/* MPI_Barrier( MPI_COMM_WORLD ); */

/* Process 1 */ 
int  b[10]; 
int  TRUE = 1; 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh1 ); 
MPI_File_set_view( fh1, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_set_atomicity( fh1, TRUE ); 
/* MPI_Barrier( MPI_COMM_WORLD ); */ 
MPI_File_read_at(fh1, 0, b, 10, MPI_INT, &status);

A user may guarantee that the write on process 0 precedes the read on process 1 by imposing temporal order with, for example, calls to MPI_BARRIER.

Advice to users.

Routines other than MPI_BARRIER may be used to impose temporal order. In the example above, process 0 could use MPI_SEND to send a 0 byte message, received by process 1 using MPI_RECV. ( End of advice to users.)
Alternatively, a user can impose consistency with nonatomic mode set:

/* Process 0 */ 
int  i, a[10]; 
for ( i=0;i<10;i++) 
   a[i] = 5; 
 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh0 ); 
MPI_File_set_view( fh0, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_write_at(fh0, 0, a, 10, MPI_INT, &status ); 
MPI_File_sync( fh0 ); 
MPI_Barrier( MPI_COMM_WORLD ); 
MPI_File_sync( fh0 );

/* Process 1 */ 
int  b[10]; 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh1 ); 
MPI_File_set_view( fh1, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_sync( fh1 ); 
MPI_Barrier( MPI_COMM_WORLD ); 
MPI_File_sync( fh1 ); 
MPI_File_read_at(fh1, 0, b, 10, MPI_INT, &status );

The ``sync-barrier-sync'' construct is required because:

The barrier ensures that the write on process 0 occurs before the read on process 1.
The first sync guarantees that the data written by all processes is transferred to the storage device.
The second sync guarantees that all data which has been transferred to the storage device is visible to all processes. (This does not affect process 0 in this example.)

The following program represents an erroneous attempt to achieve consistency by eliminating the apparently superfluous second ``sync'' call for each process.

/* ----------------  THIS EXAMPLE IS ERRONEOUS --------------- */ 
/* Process 0 */ 
int  i, a[10]; 
for ( i=0;i<10;i++) 
   a[i] = 5; 
 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh0 ); 
MPI_File_set_view( fh0, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_write_at(fh0, 0, a, 10, MPI_INT, &status ); 
MPI_File_sync( fh0 ); 
MPI_Barrier( MPI_COMM_WORLD );

/* Process 1 */ 
int  b[10]; 
MPI_File_open( MPI_COMM_WORLD, "workfile",  
               MPI_MODE_RDWR | MPI_MODE_CREATE, MPI_INFO_NULL, &fh1 ); 
MPI_File_set_view( fh1, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_Barrier( MPI_COMM_WORLD ); 
MPI_File_sync( fh1 ); 
MPI_File_read_at(fh1, 0, b, 10, MPI_INT, &status ); 
 
/* ----------------  THIS EXAMPLE IS ERRONEOUS --------------- */

The above program also violates the MPI rule against out-of-order collective operations and will deadlock for implementations in which MPI_FILE_SYNC blocks.

Advice to users.

Some implementations may choose to implement MPI_FILE_SYNC as a temporally synchronizing function. When using such an implementation, the ``sync-barrier-sync'' construct above can be replaced by a single ``sync.'' The results of using such code with an implementation for which MPI_FILE_SYNC is not temporally synchronizing is undefined. ( End of advice to users.)

Up: Consistency and Semantics Next: Asynchronous I/O Previous: File Size

314.1. Asynchronous I/O

Up: Examples Next: I/O Error Handling Previous: Examples

The behavior of asynchronous I/O operations is determined by applying the rules specified above for synchronous I/O operations.

The following examples all access a preexisting file ``myfile.'' Word 10 in myfile initially contains the integer 2. Each example writes and reads word 10.

First consider the following code fragment:

int a = 4, b, TRUE=1; 
MPI_File_open( MPI_COMM_WORLD, "myfile",  
               MPI_MODE_RDWR, MPI_INFO_NULL, &fh ); 
MPI_File_set_view( fh, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
/* MPI_File_set_atomicity( fh, TRUE );   Use this to set atomic mode. */ 
MPI_File_iwrite_at(fh, 10, &a, 1, MPI_INT, &reqs[0]); 
MPI_File_iread_at(fh,  10, &b, 1, MPI_INT, &reqs[1]); 
MPI_Waitall(2, reqs, statuses);

For asynchronous data access operations, MPI specifies that the access occurs at any time between the call to the asynchronous data access routine and the return from the corresponding request complete routine. Thus, executing either the read before the write, or the write before the read is consistent with program order. If atomic mode is set, then MPI guarantees sequential consistency, and the program will read either 2 or 4 into b. If atomic mode is not set, then sequential consistency is not guaranteed and the program may read something other than 2 or 4 due to the conflicting data access.

Similarly, the following code fragment does not order file accesses:

int a = 4, b; 
MPI_File_open( MPI_COMM_WORLD, "myfile",  
               MPI_MODE_RDWR, MPI_INFO_NULL, &fh ); 
MPI_File_set_view( fh, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
/* MPI_File_set_atomicity( fh, TRUE );   Use this to set atomic mode. */ 
MPI_File_iwrite_at(fh, 10, &a, 1, MPI_INT, &reqs[0]); 
MPI_File_iread_at(fh,  10, &b, 1, MPI_INT, &reqs[1]); 
MPI_Wait(&reqs[0], &status); 
MPI_Wait(&reqs[1], &status);

If atomic mode is set, either 2 or 4 will be read into b. Again, MPI does not guarantee sequential consistency in nonatomic mode.

On the other hand, the following code fragment:

int a = 4, b; 
MPI_File_open( MPI_COMM_WORLD, "myfile",  
               MPI_MODE_RDWR, MPI_INFO_NULL, &fh ); 
MPI_File_set_view( fh, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_iwrite_at(fh, 10, &a, 1, MPI_INT, &reqs[0]); 
MPI_Wait(&reqs[0], &status); 
MPI_File_iread_at(fh,  10, &b, 1, MPI_INT, &reqs[1]); 
MPI_Wait(&reqs[1], &status);

defines the same ordering as:

int a = 4, b; 
MPI_File_open( MPI_COMM_WORLD, "myfile",  
               MPI_MODE_RDWR, MPI_INFO_NULL, &fh ); 
MPI_File_set_view( fh, 0, MPI_INT, MPI_INT, "native", MPI_INFO_NULL ); 
MPI_File_write_at(fh, 10, &a, 1, MPI_INT, &status ); 
MPI_File_read_at(fh,  10, &b, 1, MPI_INT, &status );

Since

nonconcurrent operations on a single file handle are sequentially consistent, and
the program fragments specify an order for the operations,

MPI guarantees that both program fragments will read the value 4 into b. There is no need to set atomic mode for this example.

Similar considerations apply to conflicting accesses of the form:

MPI_File_iwrite_all(fh,...); 
MPI_File_iread_all(fh,...); 
MPI_Waitall(...);

In addition, as mentioned in Section Nonblocking Collective File Operations , nonblocking collective I/O operations have to be called in the same order on the file handle by all processes.

Similar considerations apply to conflicting accesses of the form:

MPI_File_write_all_begin(fh,...); 
MPI_File_iread(fh,...); 
MPI_Wait(fh,...); 
MPI_File_write_all_end(fh,...);

Recall that constraints governing consistency and semantics are not relevant to the following:

MPI_File_write_all_begin(fh,...); 
MPI_File_read_all_begin(fh,...); 
MPI_File_read_all_end(fh,...); 
MPI_File_write_all_end(fh,...);

since split collective operations on the same file handle may not overlap (see Section Split Collective Data Access Routines ).

Up: Examples Next: I/O Error Handling Previous: Examples

Return to MPI-3.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-3.1 of June 4, 2015
HTML Generated on June 4, 2015