1.6 Nonblocking Read

PnetCDF nonblocking APIs allow users to aggregate multiple (small) requests into a single large one, and hence to achieve a better I/O performance. Programming of nonblocking APIs consists of two parts: posting the nonblocking requests and later committing the requests. APIs ncmpi_wait_all and ncmpi_wait commit the pending requests by aggregating them into a single MPI-IO call. Here is a typical sequence of PnetCDF API calls to use nonblocking APIs to read from a netCDF file:

    ncmpi_open                          /* open an existing netCDF file: enter data mode */
         ... 
       ncmpi_iget_var<kind>_<type>      /* post a nonblocking read request to a variable */
         ... 
       ncmpi_iget_var<kind>_<type>      /* post another nonblocking read request to the same or a different variable */
         ... 
       ncmpi_wait_all                   /* commit the posted nonblocking requests */
         ... 
    ncmpi_close                         /* close the netCDF file */

Nonblocking APIs are not collective. They can be called in either collective or independent data mode. Starting from 1.7.0, the nonblocking APIs can be called in define mode as well. Multiple nonblocking I/O requests can be posted and the number of nonblocking requests can be different among MPI processes.

There are two wait APIs: ncmpi_wait_all() is to be called in the collective data mode and ncmpi_wait() in the independent data mode.

Limitations

For "iget" APIs, users should not alter the contents of the read buffer once the request is posted until the wait API call is returned. Any change to the buffer in between will result in unexpected error.

The read buffer used in one "iget" call should not be reused in another "get/put" API call (blocking or nonblocking) and two buffers used in different "iget/get/iput/put" API calls should not overlap. Currently, PnetCDF does not detect whether user buffers are reused or overlapped.

Examples

int req[NUM_VARS], statuses[NUM_VARS];

/* read from one variable at a time using iget */
for (i=0; i<NUM_VARS; i++) {
     err = ncmpi_iget_vara_int(ncid, varids[i], starts, counts, buf[i], &req[i]);
     handle_error(err);
}

/* wait for the nonblocking reads to complete */
err = ncmpi_wait_all(ncid, NUM_VARS, req, statuses);
if (err != NC_NOERR) {
    handle_error(err);

    /* check errors for individual requests */
    for (i=0; i<NUM_VARS; i++)
        handle_error(statuses[i]);
}