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


4.27 Nonblocking Read a Subarray: ncmpi_iget_<kind>_<type>

The ncmpi_iget_var<kind>_<type> family of functions is the nonblocking version of the read functions. The nonblocking APIs have an additional argument, request. It can be used later to query the status of the put operation or wait for the write to complete.

A nonblocking get call indicates that the PnetCDF may start using (possible altering the contents of) the get buffer. The caller should not access any part of the get buffer after a nonblocking get is called, until the get completes.

<kind>: <none>, ’1’, ’a’, ’s’, or ’m’.

Data types

<type > for API names <C type> for API arguments
text char
schar signed char
short short
int int
float float
double double
uchar unsigned char
ushort unsigned short
uint unsigned int
longlong long long
ulonglong unsigned longlong

Operational Mode

Prior to version 1.7.0, nonblocking APIs must be called while the netCDF file is in data mode. Starting from 1.7.0, nonblocking APIs can be called in either define or data mode. This API family can be called in either collective or independent data mode.

Usage

int ncmpi_iget_var_<type>  (int                ncid,
                            int                 varid,
                            <C type>          *buf,
                            int                *request);

int ncmpi_iget_var1_<type> (int                ncid,
                            int                 varid,
                            const MPI_Offset    start[],
                            <C type>          *buf,
                            int                *request);

int ncmpi_iget_vara_<<type>(int                ncid,
                            int                 varid,
                            const MPI_Offset    start[],
                            const MPI_Offset    count[],
                            <C type>          *buf,
                            int                *request);

int ncmpi_iget_vars_<type> (int                ncid,
                            int                 varid,
                            const MPI_Offset    start[],
                            const MPI_Offset    count[],
                            const MPI_Offset    stride[],
                            <C type>          *buf,
                            int                *request);

int ncmpi_iget_varm_<type> (int                ncid,
                            int                 varid,
                            const MPI_Offset    start[],
                            const MPI_Offset    count[],
                            const MPI_Offset    stride[],
                            const MPI_Offset    imap[],
                            <C type>          *buf,
                            int                *request);

Flexible APIs:

int ncmpi_iget_var  (int                ncid,
                     int                varid,
                     void              *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);

int ncmpi_iget_var1 (int                ncid,
                     int                varid,
                     const MPI_Offset   start[],
                     void              *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);

int ncmpi_iget_vara (int                ncid,
                     int                varid,
                     const MPI_Offset   start[],
                     const MPI_Offset   count[],
                     void              *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);

int ncmpi_iget_vars (int                ncid,
                     int                varid,
                     const MPI_Offset   start[],
                     const MPI_Offset   count[],
                     const MPI_Offset   stride[],
                     void              *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);

int ncmpi_iget_varm (int                ncid,
                     int                varid,
                     const MPI_Offset   start[],
                     const MPI_Offset   count[],
                     const MPI_Offset   stride[],
                     const MPI_Offset   imap[],
                     void              *buf,
                     MPI_Offset         bufcount,
                     MPI_Datatype       buftype,
                     int               *request);
ncid

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

varid

Variable ID. Different MPI processes may use different variable IDs.

start

A vector of MPI_Offset integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable’s dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values.

count

A vector of MPI_Offset integers specifying the number of indices selected along each dimension. To read a single value, for example, specify count as (1, 1, ... , 1). The elements of count correspond, in order, to the variable’s dimensions. Hence, if the variable is a record variable, the first element of count corresponds to a count of the number of records to read.

stride

A vector of MPI_Offset integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable’s dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A NULL stride argument is treated as (1, 1, ... , 1).

imap

A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. imap[n-1] (where n is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. Intervening imap elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element’s byte-length as in netCDF 2).

buf

Pointer to the location used for computing where the data values are read; the data should be of the type appropriate for the function called. If the type of data value differs from the netCDF variable type, type conversion will occur.

bufcount

An integer indicates the number of MPI derived data type elements in the buf to be read from the file.

buftype

An MPI derived data type that describes the memory layout of buf. Starting from PnetCDF version 1.6.0, buftype can be MPI_DATATYPE_NULL. In this case, bufcount is ignored and the buf’s data type must match the type of the variable defined in the file - no data conversion will be done.

request

The nonblocking request ID returned by PnetCDF. It is to be used in a successive call to ncmpi_wait_all() or ncmpi_wait() for the completion of the nonblocking operation.

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.

Return Error Codes

ncmpi_iget_var<kind>_<type> returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

Below is an example using ncmpi_iget_vara_double to read 10 variables. For simplicity in this example, we assume that the 10 variables have been defined in the file.

#include <pnetcdf.h>
   ...
int         i;
int         ncid;           /* netCDF ID */
int         varid;          /* variable ID */
int         status;         /* error status */
int         request[10];    /* nonblocking request ID */
int         statuses[10];   /* status for individual requests */
MPI_Offset  start[10][2];   /* 10 sets of start indices */
MPI_Offset  count[10][2];   /* 10 sets of count lengths */
double     *buffers[10];    /* 10 read buffers */
   ...
status = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, MPI_INFO_NULL, &ncid);
if (status != NC_NOERR) handle_error(status);
   ...
/* define dimensions */
/* define variables */
/* set values for start and count */
/* allocate read buffers */
   ...
for (i=0; i<10; i++) {
    /* post a nonblocking read request */
    status = ncmpi_iget_vara_double(ncid, varid, start[i], count[i], buffers[i], &request[i]);
    if (status != NC_NOERR) handle_error(status);
}

/* read all 10 requests from the file at once */
status = ncmpi_wait_all(ncid, 10, request, statuses);
if (status != NC_NOERR) handle_error(status);

for (i=0; i<10; i++) /* check status for each request */
    if (statuses[i] != NC_NOERR)
        handle_error(statuses[i]);

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