4.35 Cancel pending nonblocking requests: ncmpi_cancel

This API cancels a list of pending nonblocking requests made by ncmpi_iput_var<kind>_<type>, ncmpi_iget_var<kind>_<type> or ncmpi_bput_var<kind>_<type> API families.

Operational Mode

This API is an independent subroutine.

This API can be called in either independent or collective data mode. Starting from 1.7.1, this API can also be called in define mode.

Usage

int ncmpi_cancel(int  ncid,
                 int  num_req,
                 int *req_ids,
                 int *statuses);

ncid

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

num_reqs

Number of pending requests.

Starting from 1.7.0, NC_REQ_ALL can be used, indicating to cancel all pending nonblocking requests. Starting from 1.7.1, NC_GET_REQ_ALL and NC_PUT_REQ_ALL can be used, indicating to cancel all pending nonblocking GET and PUT requests, respectively.

req_ids

An integer array contains the nonblocking request IDs. Starting from 1.7.0, the request argument can be NULL, meaning the caller does not intend to track the requests IDs. In this case, a call to ncmpi_wait_all/ncmpi_wait must use NC_REQ_ALL in its second argument "num" to flush all pending nonblocking requests.

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

statuses

An integer array of cancellation statuses, each of which corresponds to the nonblocking request IDs.

Return Error Codes

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

• NC_EBADID: The specified netCDF ID does not refer to an opened netCDF file.
• NC_EINVAL_REQUEST: Invalid nonblocking request ID (individual errors in statuses array)
• NC_ENOTSUPPORT: This API for NetCDF-4 files is not yet supported.

Example

#include <pnetcdf.h>
   ...
int i, ncid, num_reqs, err;
int req_ids[3], statuses[3];
   ...

num_reqs = 3;
err = ncmpi_cancel(ncid, num_req, req_ids, statuses);

if (err != NC_NOERR)
    handle_error(err);

for (i=0; i<num_req; i++)
    if (statuses[i] != NC_NOERR)
        handle_error(statuses[i]);