pio_darray.c File Reference

This file contains the routines that read and write distributed arrays in PIO. More...

#include <config.h>
#include <pio.h>
#include <pio_internal.h>

Functions
PIO_Offset	PIOc_set_buffer_size_limit (const PIO_Offset limit)
	Set the pio buffer size limit. More...
void	compute_buffer_init (iosystem_desc_t ios)
	Initialize the compute buffer to size PIO_CNBUFFER_LIMIT. More...
int	pio_write_darray_nc (file_desc_t *file, io_desc_t *iodesc, const int vid, void *IOBUF, void *fillvalue)
	Write a single distributed field to output. More...
int	pio_write_darray_multi_nc (file_desc_t *file, const int nvars, const int *vid, const int iodesc_ndims, MPI_Datatype basetype, const PIO_Offset *gsize, const int maxregions, io_region *firstregion, const PIO_Offset llen, const int maxiobuflen, const int num_aiotasks, void *IOBUF, const int *frame)
	Write a set of one or more aggregated arrays to output file. More...
int	pio_write_darray_multi_nc_serial (file_desc_t *file, const int nvars, const int *vid, const int iodesc_ndims, MPI_Datatype basetype, const PIO_Offset *gsize, const int maxregions, io_region *firstregion, const PIO_Offset llen, const int maxiobuflen, const int num_aiotasks, void *IOBUF, const int *frame)
	Write a set of one or more aggregated arrays to output file in serial mode. More...
int	PIOc_write_darray_multi (const int ncid, const int *vid, const int ioid, const int nvars, const PIO_Offset arraylen, void *array, const int *frame, void **fillvalue, bool flushtodisk)
	Write one or more arrays with the same IO decomposition to the file. More...
int	PIOc_write_darray (const int ncid, const int vid, const int ioid, const PIO_Offset arraylen, void *array, void *fillvalue)
	Write a distributed array to the output file. More...
int	pio_read_darray_nc (file_desc_t *file, io_desc_t *iodesc, const int vid, void *IOBUF)
	Read an array of data from a file to the (parallel) IO library. More...
int	pio_read_darray_nc_serial (file_desc_t *file, io_desc_t *iodesc, const int vid, void *IOBUF)
	Read an array of data from a file to the (serial) IO library. More...
int	PIOc_read_darray (const int ncid, const int vid, const int ioid, const PIO_Offset arraylen, void *array)
	Read a field from a file to the IO library. More...

Variables
PIO_Offset	PIO_BUFFER_SIZE_LIMIT = 10485760
bufsize	PIO_CNBUFFER_LIMIT = 33554432

Detailed Description

This file contains the routines that read and write distributed arrays in PIO.

When arrays are distributed, each processor holds some of the array. Only by combining the distributed arrays from all processor can the full array be obtained.

Author

Jim Edwards, Ed Hartnett

Function Documentation

compute_buffer_init()

void compute_buffer_init

(

iosystem_desc_t

ios

)

Initialize the compute buffer to size PIO_CNBUFFER_LIMIT.

This routine initializes the compute buffer pool if the bget memory management is used. If malloc is used (that is, PIO_USE_MALLOC is non zero), this function does nothing.

Parameters

ios	the iosystem descriptor which will use the new buffer

pio_read_darray_nc()

int pio_read_darray_nc	(	file_desc_t *	file,
		io_desc_t *	iodesc,
		const int	vid,
		void *	IOBUF
	)

Read an array of data from a file to the (parallel) IO library.

Parameters

file	a pointer to the open file descriptor for the file that will be written to
iodesc	a pointer to the defined iodescriptor for the buffer
vid	the variable id to be read
IOBUF	the buffer to be read into from this mpi task

Returns

0 on success, error code otherwise.

pio_read_darray_nc_serial()

int pio_read_darray_nc_serial	(	file_desc_t *	file,
		io_desc_t *	iodesc,
		const int	vid,
		void *	IOBUF
	)

Read an array of data from a file to the (serial) IO library.

Parameters

file	a pointer to the open file descriptor for the file that will be written to
iodesc	a pointer to the defined iodescriptor for the buffer
vid	the variable id to be read.
IOBUF	the buffer to be read into from this mpi task

Returns

pio_write_darray_multi_nc()

int pio_write_darray_multi_nc	(	file_desc_t *	file,
		const int	nvars,
		const int *	vid,
		const int	iodesc_ndims,
		MPI_Datatype	basetype,
		const PIO_Offset *	gsize,
		const int	maxregions,
		io_region *	firstregion,
		const PIO_Offset	llen,
		const int	maxiobuflen,
		const int	num_aiotasks,
		void *	IOBUF,
		const int *	frame
	)

Write a set of one or more aggregated arrays to output file.

This routine is used if aggregation is enabled, data is already on the io-tasks

Parameters

file	a pointer to the open file descriptor for the file that will be written to
nvars	the number of variables to be written with this decomposition
vid	an array of the variable ids to be written
iodesc_ndims	the number of dimensions explicitly in the iodesc
basetype	the basic type of the minimal data unit
gsize	array of the global dimensions of the field to be written
maxregions	max number of blocks to be written from this iotask
firstregion	pointer to the first element of a linked list of region descriptions.
llen	length of the iobuffer on this task for a single field
maxiobuflen	maximum llen participating
num_aiotasks	actual number of iotasks participating
IOBUF	the buffer to be written from this mpi task
frame	the frame or record dimension for each of the nvars variables in IOBUF

Returns

0 for success, error code otherwise.

pio_write_darray_multi_nc_serial()

int pio_write_darray_multi_nc_serial	(	file_desc_t *	file,
		const int	nvars,
		const int *	vid,
		const int	iodesc_ndims,
		MPI_Datatype	basetype,
		const PIO_Offset *	gsize,
		const int	maxregions,
		io_region *	firstregion,
		const PIO_Offset	llen,
		const int	maxiobuflen,
		const int	num_aiotasks,
		void *	IOBUF,
		const int *	frame
	)

Write a set of one or more aggregated arrays to output file in serial mode.

This routine is used if aggregation is enabled, data is already on the io-tasks

Parameters

file	a pointer to the open file descriptor for the file that will be written to
nvars	the number of variables to be written with this decomposition
vid	an array of the variable ids to be written
iodesc_ndims	the number of dimensions explicitly in the iodesc
basetype	: the basic type of the minimal data unit
gsize	: array of the global dimensions of the field to be written
maxregions	: max number of blocks to be written from this iotask
firstregion	: pointer to the first element of a linked list of region descriptions.
llen	: length of the iobuffer on this task for a single field
maxiobuflen	: maximum llen participating
num_aiotasks	: actual number of iotasks participating
IOBUF	the buffer to be written from this mpi task
frame	: the frame or record dimension for each of the nvars variables in IOBUF

Returns

0 for success, error code otherwise.

pio_write_darray_nc()

int pio_write_darray_nc	(	file_desc_t *	file,
		io_desc_t *	iodesc,
		const int	vid,
		void *	IOBUF,
		void *	fillvalue
	)

Write a single distributed field to output.

This routine is only used if aggregation is off.

Parameters

file	a pointer to the open file descriptor for the file that will be written to
iodesc	a pointer to the defined iodescriptor for the buffer
vid	the variable id to be written
IOBUF	the buffer to be written from this mpi task
fillvalue	the optional fillvalue to be used for missing data in this buffer

Returns

0 for success, error code otherwise.

PIOc_read_darray()

int PIOc_read_darray	(	const int	ncid,
		const int	vid,
		const int	ioid,
		const PIO_Offset	arraylen,
		void *	array
	)

Read a field from a file to the IO library.

Parameters

ncid	identifies the netCDF file
vid	the variable ID to be read
ioid	the I/O description ID as passed back by PIOc_InitDecomp().
arraylen	the length of the array to be read. This is the length of the distrubited array. That is, the length of the portion of the data that is on the processor.
array	pointer to the data to be read. This is a pointer to the distributed portion of the array that is on this processor.

Returns

0 for success, error code otherwise.

PIOc_set_buffer_size_limit()

PIO_Offset PIOc_set_buffer_size_limit

(

const PIO_Offset

limit

)

Set the pio buffer size limit.

This is the size of the data buffer on the IO nodes.

The pio_buffer_size_limit will only apply to files opened after the setting is changed.

Parameters

limit

the size of the buffer on the IO nodes

Returns

The previous limit setting.

PIOc_write_darray()

int PIOc_write_darray	(	const int	ncid,
		const int	vid,
		const int	ioid,
		const PIO_Offset	arraylen,
		void *	array,
		void *	fillvalue
	)

Write a distributed array to the output file.

This routine aggregates output on the compute nodes and only sends it to the IO nodes when the compute buffer is full or when a flush is triggered.

Parameters

ncid	the ncid of the open netCDF file.
vid	the variable ID returned by PIOc_def_var().
ioid	the I/O description ID as passed back by PIOc_InitDecomp().
arraylen	the length of the array to be written. This is the length of the distrubited array. That is, the length of the portion of the data that is on the processor.
array	pointer to the data to be written. This is a pointer to the distributed portion of the array that is on this processor.
fillvalue	pointer to the fill value to be used for missing data.

Returns

0 for success, non-zero error code for failure.

PIOc_write_darray_multi()

int PIOc_write_darray_multi	(	const int	ncid,
		const int *	vid,
		const int	ioid,
		const int	nvars,
		const PIO_Offset	arraylen,
		void *	array,
		const int *	frame,
		void **	fillvalue,
		bool	flushtodisk
	)

Write one or more arrays with the same IO decomposition to the file.

Parameters

ncid	identifies the netCDF file
vid	an array of the variable ids to be written
ioid	the I/O description ID as passed back by PIOc_InitDecomp().
nvars	the number of variables to be written with this decomposition
arraylen	the length of the array to be written. This is the length of the distrubited array. That is, the length of the portion of the data that is on the processor.
array	pointer to the data to be written. This is a pointer to the distributed portion of the array that is on this processor.
frame	the frame or record dimension for each of the nvars variables in IOBUF
fillvalue	pointer to the fill value to be used for missing data.
flushtodisk

Returns

0 for success, error code otherwise.