Skip to content

Commit

Permalink
Merge pull request #1214 from NCAR/ejh_doc
Browse files Browse the repository at this point in the history 
fixed up documentation
  • Loading branch information
@edhartnett
edhartnett authored Sep 22, 2017
2 parents 4b8af28 + 3f91a92 commit 1efb215
Showing 1 changed file with 52 additions and 49 deletions.
101 changes: 52 additions & 49 deletions src/clib/pio_internal.h
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @file
* Private headers and defines for the PIO C interface.
* @author Jim Edwards
* @author Jim Edwards, Ed Hartnett
* @date 2014
*
* @see http://code.google.com/p/parallelio/
Expand Down Expand Up @@ -100,31 +100,58 @@ extern "C" {
int pio_err(iosystem_desc_t *ios, file_desc_t *file, int err_num, const char *fname,
int line);

/* Check return from MPI function and print error message. */
void CheckMPIReturn(int ierr, const char *file, int line);

/* Print error message and abort. */
void piodie(const char *msg, const char *fname, int line);

/* Assert that an expression is true. */
void pioassert(bool exp, const char *msg, const char *fname, int line);

/* Check the return code from an MPI function call. */
int check_mpi(file_desc_t *file, int mpierr, const char *filename, int line);

/* Check the return code from an MPI function call. */
int check_mpi2(iosystem_desc_t *ios, file_desc_t *file, int mpierr, const char *filename,
int line);

/* Check the return code from a netCDF call. */
int check_netcdf(file_desc_t *file, int status, const char *fname, int line);

/* Check the return code from a netCDF call, with ios pointer. */
int check_netcdf2(iosystem_desc_t *ios, file_desc_t *file, int status,
const char *fname, int line);

/* For async cases, this runs on IO tasks and listens for messages. */
int pio_msg_handler2(int io_rank, int component_count, iosystem_desc_t **iosys,
MPI_Comm io_comm);

void pio_get_env(void);
/* List operations for iosystem list. */
int pio_add_to_iosystem_list(iosystem_desc_t *ios);
int pio_delete_iosystem_from_list(int piosysid);
iosystem_desc_t *pio_get_iosystem_from_id(int iosysid);

/* List operations for decomposition list. */
int pio_add_to_iodesc_list(io_desc_t *iodesc);
io_desc_t *pio_get_iodesc_from_id(int ioid);
int pio_delete_iodesc_from_list(int ioid);
int pio_num_iosystem(int *niosysid);

/* Allocate and initialize storage for decomposition information. */
int malloc_iodesc(iosystem_desc_t *ios, int piotype, int ndims, io_desc_t **iodesc);

/* List operations for file_desc_t list. */
int pio_get_file(int ncid, file_desc_t **filep);
int pio_delete_file_from_list(int ncid);
void pio_add_to_file_list(file_desc_t *file);
/* Add a var_desc_t to a varlist. */

/* List operations for var_desc_t list. */
int add_to_varlist(int varid, int rec_var, int pio_type, int pio_type_size,
MPI_Datatype mpi_type, int mpi_type_size, var_desc_t **varlist);

/* Find a var_desc_t in a varlist. */
int get_var_desc(int varid, var_desc_t **varlist, var_desc_t **var_desc);

/* Delete a var_desc_t from a varlist. */
int delete_var_desc(int varid, var_desc_t **varlist);

void pio_push_request(file_desc_t *file, int request);

/* Create a file (internal function). */
int PIOc_createfile_int(int iosysid, int *ncidp, int *iotype, const char *filename, int mode);

Expand All @@ -133,28 +160,12 @@ extern "C" {
int PIOc_openfile_retry(int iosysid, int *ncidp, int *iotype, const char *filename, int mode,
int retry);

iosystem_desc_t *pio_get_iosystem_from_id(int iosysid);
int pio_add_to_iosystem_list(iosystem_desc_t *ios);

/* Check the return code from a netCDF call. */
int check_netcdf(file_desc_t *file, int status, const char *fname, int line);

/* Check the return code from a netCDF call, with ios pointer. */
int check_netcdf2(iosystem_desc_t *ios, file_desc_t *file, int status,
const char *fname, int line);

/* Given PIO type, find MPI type and type size. */
int find_mpi_type(int pio_type, MPI_Datatype *mpi_type, int *type_size);

/* Check whether an IO type is valid for this build. */
int iotype_is_valid(int iotype);

/* Print error message and abort. */
void piodie(const char *msg, const char *fname, int line);

/* Assert that an expression is true. */
void pioassert(bool exp, const char *msg, const char *fname, int line);

/* Compute start and count values for each io task for a decomposition. */
int CalcStartandCount(int pio_type, int ndims, const int *gdims, int num_io_procs,
int myiorank, PIO_Offset *start, PIO_Offset *count, int *num_aiotasks);
Expand All @@ -166,17 +177,16 @@ extern "C" {
/* Create the MPI communicators needed by the subset rearranger. */
int default_subset_partition(iosystem_desc_t *ios, io_desc_t *iodesc);

/* Check return from MPI function and print error message. */
void CheckMPIReturn(int ierr, const char *file, int line);

/* Like MPI_Alltoallw(), but with flow control. */
int pio_swapm(void *sendbuf, int *sendcounts, int *sdispls, MPI_Datatype *sendtypes,
void *recvbuf, int *recvcounts, int *rdispls, MPI_Datatype *recvtypes,
MPI_Comm comm, rearr_comm_fc_opt_t *fc);

/* Return the greatest common devisor of array ain as int_64. */
long long lgcd_array(int nain, long long* ain);

void PIO_Offset_size(MPI_Datatype *dtype, int *tsize);
/* Look for the largest block of data for io which can be
* expressed in terms of start and count. */
PIO_Offset GCDblocksize(int arrlen, const PIO_Offset *arr_in);

/* Convert an index into dimension values. */
Expand All @@ -189,6 +199,9 @@ extern "C" {
int determine_fill(iosystem_desc_t *ios, io_desc_t *iodesc, const int *gsize,
const PIO_Offset *compmap);

/* Allocation memory for a data region. */
int alloc_region2(iosystem_desc_t *ios, int ndims, io_region **region);

/* Set start and count so that they describe the first region in map.*/
PIO_Offset find_region(int ndims, const int *gdims, int maplen, const PIO_Offset *map,
PIO_Offset *start, PIO_Offset *count);
Expand All @@ -203,6 +216,9 @@ extern "C" {
int region_size, int region_stride, const int *max_size,
PIO_Offset *count);

/* Free a region list. */
void free_region_list(io_region *top);

/* Compare sets of rearranger options. */
bool cmp_rearr_opts(const rearr_opt_t *rearr_opts, const rearr_opt_t *exp_rearr_opts);

Expand All @@ -217,21 +233,17 @@ extern "C" {
int subset_rearrange_create(iosystem_desc_t *ios, int maplen, PIO_Offset *compmap, const int *gsize,
int ndim, io_desc_t *iodesc);


/* Create a box rearranger. */
int box_rearrange_create(iosystem_desc_t *ios, int maplen, const PIO_Offset *compmap, const int *gsize,
int ndim, io_desc_t *iodesc);


/* Move data from IO tasks to compute tasks. */
int rearrange_io2comp(iosystem_desc_t *ios, io_desc_t *iodesc, void *sbuf, void *rbuf);

/* Move data from compute tasks to IO tasks. */
int rearrange_comp2io(iosystem_desc_t *ios, io_desc_t *iodesc, void *sbuf, void *rbuf,
int nvars);

/* Allocate and initialize storage for decomposition information. */
int malloc_iodesc(iosystem_desc_t *ios, int piotype, int ndims, io_desc_t **iodesc);
void performance_tune_rearranger(iosystem_desc_t *ios, io_desc_t *iodesc);

/* Flush contents of multi-buffer to disk. */
Expand All @@ -240,12 +252,6 @@ extern "C" {
/* Compute the size that the IO tasks will need to hold the data. */
int compute_maxIObuffersize(MPI_Comm io_comm, io_desc_t *iodesc);

/* Allocation memory for a data region. */
int alloc_region2(iosystem_desc_t *ios, int ndims, io_region **region);

/* Delete an entry from the lost of open IO systems. */
int pio_delete_iosystem_from_list(int piosysid);

/* Find greatest commond divisor. */
int gcd(int a, int b);

Expand All @@ -255,12 +261,13 @@ extern "C" {
/* Find greatest commond divisor in an array. */
int gcd_array(int nain, int *ain);

void free_region_list(io_region *top);

/* Convert a global coordinate value into a local array index. */
PIO_Offset coord_to_lindex(int ndims, const PIO_Offset *lcoord, const PIO_Offset *count);

/* Returns the smallest power of 2 greater than or equal to i. */
int ceil2(int i);

/* ??? */
int pair(int np, int p, int k);

/* Create MPI datatypes used for comp2io and io2comp data transfers. */
Expand All @@ -270,16 +277,20 @@ extern "C" {
* transfers. */
int create_mpi_datatypes(MPI_Datatype basetype, int msgcnt, const PIO_Offset *mindex,
const int *mcount, int *mfrom, MPI_Datatype *mtype);

/* Used by subset rearranger to sort map. */
int compare_offsets(const void *a, const void *b) ;

/* Print a trace statement, for debugging. */
void print_trace (FILE *fp);

/* Print diagonstic info to stdout. */
void cn_buffer_report(iosystem_desc_t *ios, bool collective);

/* Initialize the compute buffer. */
int compute_buffer_init(iosystem_desc_t *ios);

/* Free the buffer pool. */
void free_cn_buffer_pool(iosystem_desc_t *ios);

/* Flush PIO's data buffer. */
Expand All @@ -289,13 +300,6 @@ extern "C" {
void compute_one_dim(int gdim, int ioprocs, int rank, PIO_Offset *start,
PIO_Offset *count);

/* Check the return code from an MPI function call. */
int check_mpi(file_desc_t *file, int mpierr, const char *filename, int line);

/* Check the return code from an MPI function call. */
int check_mpi2(iosystem_desc_t *ios, file_desc_t *file, int mpierr, const char *filename,
int line);

/* Darray support functions. */

/* Write aggregated arrays to file using parallel I/O (netCDF-4 parallel/pnetcdf) */
Expand Down Expand Up @@ -324,7 +328,6 @@ extern "C" {
void *buf);
int PIOc_get_var_tc(int ncid, int varid, nc_type xtype, void *buf);


/* Generalized put functions. */
int PIOc_put_vars_tc(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count,
const PIO_Offset *stride, nc_type xtype, const void *buf);
Expand Down

0 comments on commit 1efb215

Please sign in to comment.