Next: , Previous: , Up: Variables   [Index]

4.32 Nonblocking I/O Completion: ncmpi_wait/wait_all

APIs ncmpi_wait and ncmpi_wait_all are blocking calls that wait for the completion of nonblocking I/O requests. The nonblocking requests intended to complete are specified in the array of request IDs, array_of_requests[]. The request IDs can be all or a subset of nonblocking requests made earlier. The array can contain mixed read and write request IDs. Argument array_of_statuses will be returned with the statuses of individual requests. The request can be used later to query the status of the put operation or wait for the write to complete. These APIs must be called in data mode. After the called return, the caller are free to access the put buffers used in the nonblocking requests.

Operational Mode

API ncmpi_wait is an independent subroutine and must be called while the file is in independent data mode.

API ncmpi_wait_all is a collective subroutine and must be called while the file is in collective data mode.

Usage

int ncmpi_wait     (int ncid,
                    int num,
                    int array_of_requests[],
                    int array_of_statuses[]);

int ncmpi_wait_all (int ncid,
                    int num,
                    int array_of_requests[],
                    int array_of_statuses[]);
ncid

NetCDF ID, from a previous call to ncmpi_open or ncmpi_create.

num

Number of requests. It is also the array size of the next two arguments, array_of_requests and array_of_statuses.

Starting from 1.7.0, NC_REQ_ALL can be used, indicating to flush all pending nonblocking requests. In this case, the next two argument, array_of_requests and array_of_statuses will be ignored. Thus array_of_requests and array_of_statuses can be NULLs. Starting from 1.7.1, NC_GET_REQ_ALL and NC_PUT_REQ_ALL can be used, indicating to flush all pending nonblocking GET and PUT requests, respectively. In this case, the next two argument, array_of_requests and array_of_statuses will be ignored.

array_of_requests[]

A vector of integers specifying the nonblocking request IDs that were made earlier. The size of the vector should be equal to the values given in ’num’.

For each nonblocking request of a successful completion, its corresponding request ID in the array is set to NC_REQ_NULL.

array_of_statuses[]

A vector of integers returned from the call, specifying the statuses of corresponding nonblocking requests. The size of the vector should be equal to the values given in ’num’. The values can be used in a call to ncmpi_strerror() to obtain the status messages.

Starting from 1.7.0, this argument can be NULL, indicating the caller’s intention to ignore the errors for individual nonblocking requests and rely on the error code returned from this API call. The error code returned from this API call is the first error encountered while flushing the requests.

Return Error Codes

ncmpi_wait/ncmpi_wait_all returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Here is an example using ncmpi_wait_all and checking the returned status. 

#include <pnetcdf.h>
   ...
int request[10];    /* nonblocking request IDs */
int st[10];         /* nonblocking request statuses */
int i, err;
   ...

err = ncmpi_wait_all(ncid, 10, request, st);

if (err != NC_NOERR)
    fprintf(stderr, "Error on calling ncmpi_wait_all (%s)\n",
            ncmpi_strerror(err));

for (i=0; i<10; i++)
    if (st[i] != NC_NOERR)
        fprintf(stderr, "Error on request %d (%s)\n", i,
                ncmpi_strerror(st[i]));

Next: , Previous: , Up: Variables   [Index]