From 3f91a926e27d144c34f45b8e7270b52cfb8bec17 Mon Sep 17 00:00:00 2001 From: edhartnett Date: Thu, 21 Sep 2017 15:21:31 -0600 Subject: [PATCH] fixed up documentation --- src/clib/pio_internal.h | 101 +++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 49 deletions(-) diff --git a/src/clib/pio_internal.h b/src/clib/pio_internal.h index ba4a289b1f..a8947135a2 100644 --- a/src/clib/pio_internal.h +++ b/src/clib/pio_internal.h @@ -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/ @@ -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); @@ -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); @@ -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. */ @@ -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); @@ -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); @@ -217,12 +233,10 @@ 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); @@ -230,8 +244,6 @@ extern "C" { 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. */ @@ -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); @@ -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. */ @@ -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. */ @@ -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) */ @@ -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);