4.34 Inquire the metadata of attached buffer used in buffered nonblocking put APIs

A family of functions that returns information about the attached buffer used by buffered nonblocking put APIs.

ncmpi_inq_buffer_usage returns the current usage (in bytes) of the attached buffer (version 1.3.1 and later).

ncmpi_inq_buffer_size returns the size (in bytes) of the attached buffer (version 1.6.0 and later).

Operational Mode

These APIs are independent subroutines.

These APIs can be called while the file is in either define or data mode (collective or independent).

Usage

int ncmpi_inq_buffer_usage(int         ncid,
                           MPI_Offset *usage);

int ncmpi_inq_buffer_size (int         ncid,
                           MPI_Offset *buf_size);

ncid

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

usage

The current usage of the internal buffer. Its value in bytes shows much space is left for any further buffered APIs calls. Prior to 1.9.0, if this argument is NULL, error code NC_EINVAL is returned. Starting from 1.9.0, if this argument is NULL, it is ignored.

buf_size

The size (in number of bytes) of the attached buffer. This value is the same as the one used in a call to ncmpi_buffer_attach() earlier. Prior to 1.9.0, if this argument is NULL, error code NC_EINVAL is returned. Starting from 1.9.0, if this argument is NULL, it is ignored.

Return Error Codes

ncmpi_inq_buffer_usage/ncmpi_inq_buffer_size 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_ENULLABUF: no attached buffer is found
• NC_ENOTSUPPORT: This API for NetCDF-4 files is not yet supported.

Example

Here is an example using ncmpi_inq_buffer_usage and ncmpi_inq_buffer_size.

#include <pnetcdf.h>
   ...
int varid1, varid2, varid3, nreqs, err;
int i_buf[8], req_ids[10], st[10];
long long ll_buf[10];
double d_buf[20], d2_buf[12];
MPI_Offset start1[2], count1[2], start2[3], count2[3];
MPI_Offset start3[2], count3[2], usage, buf_size;
   ...

/* attach buffer of size 1MB */
status = ncmpi_buffer_attach(ncid, 1048576);
if (status != NC_NOERR) handle_error(status);

/* several writes into netCDF variables */
status = ncmpi_bput_vara_double(ncid, varid1, start1, count1, d_buf, &request[0]);
if (status != NC_NOERR) handle_error(status);

status = ncmpi_bput_vara_int(ncid, varid2, start2, count2, i_buf, &request[1]);
if (status != NC_NOERR) handle_error(status);

status = ncmpi_bput_vars_longlong(ncid, varid3, start3, count3, stride3, ll_buf, &request[2]);
if (status != NC_NOERR) handle_error(status);

/* check the usage of the buffer */
status = ncmpi_inq_buffer_usage(ncid, &usage);
if (status != NC_NOERR) handle_error(status);

/* inquire the attached buffer size */
status = ncmpi_inq_buffer_size(ncid, &buf_size);
if (status != NC_NOERR) handle_error(status);

status = ncmpi_bput_var_double(ncid, varid4, d2_buf, &request[3]);
if (status != NC_NOERR) handle_error(status);

/* wait here for all 4 nonblocking APIs to complete */
status = ncmpi_wait_all(ncid, 4, request, st);
if (status != NC_NOERR) handle_error(status);

/* release buffer */
status = ncmpi_buffer_detach(ncid);
if (status != NC_NOERR) handle_error(status);