Merge pull request ESMCI#1567 from NCAR/ejh_ncint_mem

Turn on rest of ncint C test, now with no leaks, change some function names, begin to add docs
jedwards4b · Jul 17, 2019 · f29d6b5 · f29d6b5
2 parents 91c0564 + 0d892ef
commit f29d6b5
Show file tree

Hide file tree

Showing 13 changed files with 140 additions and 125 deletions.
diff --git a/configure.ac b/configure.ac
@@ -161,9 +161,9 @@ if test "x$enable_docs" = xyes; then
    fi
    AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.f90  ../src/flib/pio.F90  ../src/flib/pio_kinds.F90  ../src/flib/piolib_mod.f90  ../src/flib/pionfatt_mod_2.f90  ../src/flib/pio_nf.F90  ../src/flib/pionfget_mod_2.f90  ../src/flib/pionfput_mod.f90  ../src/flib/pio_support.F90  ../src/flib/pio_types.F90"])
    if test "x$enable_developer_docs" = xyes; then
-      AC_SUBST([C_SRC_FILES], ["../src/clib"])
+      AC_SUBST([C_SRC_FILES], ["../src/clib ../src/ncint"])
    else
-      AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc.c ../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c ../src/clib/pioc_support.c ../src/clib/pioc.c ../src/clib/pio_file.c ../src/clib/pio.h ../src/clib/pio_get_vard.c ../src/clib/pio_put_vard.c"])
+      AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc.c ../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c ../src/clib/pioc_support.c ../src/clib/pioc.c ../src/clib/pio_file.c ../src/clib/pio.h ../src/clib/pio_get_vard.c ../src/clib/pio_put_vard.c ../src/ncint/ncint_pio.c ../src/ncint/nc_put_vard.c ../src/ncint/nc_get_vard.c"])
    fi
    AC_CONFIG_FILES([doc/Doxyfile])
 fi

diff --git a/doc/source/netcdf_integration.txt b/doc/source/netcdf_integration.txt
@@ -0,0 +1,22 @@
+/** @page netcdf_integration NetCDF API Integration
+
+The netCDF integration feature allows existing netCDF codes, in C or
+Fortran, to be easily converted to use PIO.
+
+# Building and Using PIO with NetCDF Integration
+
+In order to use netCDF integration:
+
+* The PIO configure must use the option --enable-netcdf-integration.
+
+* The latest master of the netcdf-c library must be built and used,
+and the PIO build must include the netcdf-c/include directory in its
+CPPFLAGS, in order to find internal netCDF header files needed for
+netCDF integration. (The netcdf-c library is being modified to export
+publically everything needed, so future releases of netcdf-c will no
+longer require this.)
+
+Once PIO is build for netCDF integration, it provides the nc_* and
+nf_* functions required to fully integrate PIO and netCDF.
+
+*/
diff --git a/doc/source/users_guide.txt b/doc/source/users_guide.txt
@@ -12,6 +12,7 @@ releases.
  - @ref decomp
  - @ref error
  - @ref examp
+ - @ref netcdf_integration
  - @ref faq
  - @ref api
  - @ref c_api

diff --git a/src/clib/pio.h b/src/clib/pio.h
@@ -1,7 +1,7 @@
 /**
  * @file
  * Public headers for the PIO C interface.
- * @author Jim Edwards
+ * @author Jim Edwards, Ed Hartnett
  * @date  2014
  *
  * @see https://github.com/NCAR/ParallelIO
@@ -1247,74 +1247,77 @@ extern "C" {
                                 const unsigned long long *op);
 
     /* These functions are for the netCDF integration layer. */
-    int nc_init_intracomm(MPI_Comm comp_comm, int num_iotasks, int stride, int base, int rearr,
-                          int *iosysidp);
+    int nc_def_iosystemm(MPI_Comm comp_comm, int num_iotasks, int stride, int base, int rearr,
+                         int *iosysidp);
 
     /* Set the default IOsystem ID. */
     int nc_set_iosystem(int iosysid);
 
     /* Get the default IOsystem ID. */
     int nc_get_iosystem(int *iosysid);
 
+    /* Release the resources associated with an iosystem. */
     int nc_free_iosystem(int iosysid);
 
-    int nc_init_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen,
-                       int maplen, const size_t *compmap, int *ioidp,
-                       int rearranger, const size_t *iostart,
-                       const size_t *iocount);
+    /* Define a decomposition for distributed arrays. */
+    int nc_def_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen,
+                      int maplen, const size_t *compmap, int *ioidp,
+                      int rearranger, const size_t *iostart,
+                      const size_t *iocount);
 
+    /* Release resources associated with a decomposition. */
     int nc_free_decomp(int ioid);
 
-    /* Data reads - vard. */
+    /* Data reads - read a distributed array. */
     int nc_get_vard(int ncid, int varid, int decompid, const size_t recnum, void *buf);
     int nc_get_vard_text(int ncid, int varid, int decompid, const size_t recnum,
-                           char *buf);
+                         char *buf);
     int nc_get_vard_schar(int ncid, int varid, int decompid, const size_t recnum,
-                            signed char *buf);
+                          signed char *buf);
     int nc_get_vard_short(int ncid, int varid, int decompid, const size_t recnum,
-                            short *buf);
+                          short *buf);
     int nc_get_vard_int(int ncid, int varid, int decompid, const size_t recnum,
-                          int *buf);
+                        int *buf);
     int nc_get_vard_float(int ncid, int varid, int decompid, const size_t recnum,
-                            float *buf);
+                          float *buf);
     int nc_get_vard_double(int ncid, int varid, int decompid, const size_t recnum,
-                             double *buf);
+                           double *buf);
     int nc_get_vard_uchar(int ncid, int varid, int decompid, const size_t recnum,
-                            unsigned char *buf);
+                          unsigned char *buf);
     int nc_get_vard_ushort(int ncid, int varid, int decompid, const size_t recnum,
-                             unsigned short *buf);
+                           unsigned short *buf);
     int nc_get_vard_uint(int ncid, int varid, int decompid, const size_t recnum,
-                           unsigned int *buf);
+                         unsigned int *buf);
     int nc_get_vard_longlong(int ncid, int varid, int decompid, const size_t recnum,
-                               long long *buf);
+                             long long *buf);
     int nc_get_vard_ulonglong(int ncid, int varid, int decompid, const size_t recnum,
-                                unsigned long long *buf);
+                              unsigned long long *buf);
 
-    /* Data writes - vard. */
+    /* Data writes - Write a distributed array. */
     int nc_put_vard(int ncid, int varid, int decompid, const size_t recnum,
-                      const void *buf);
+                    const void *buf);
     int nc_put_vard_text(int ncid, int varid, int decompid, const size_t recnum,
-                           const char *op);
+                         const char *op);
     int nc_put_vard_schar(int ncid, int varid, int decompid, const size_t recnum,
-                            const signed char *op);
+                          const signed char *op);
     int nc_put_vard_short(int ncid, int varid, int decompid, const size_t recnum,
-                            const short *op);
+                          const short *op);
     int nc_put_vard_int(int ncid, int varid, int decompid, const size_t recnum,
-                          const int *op);
+                        const int *op);
     int nc_put_vard_float(int ncid, int varid, int decompid, const size_t recnum,
-                            const float *op);
+                          const float *op);
     int nc_put_vard_double(int ncid, int varid, int decompid, const size_t recnum,
-                             const double *op);
+                           const double *op);
     int nc_put_vard_uchar(int ncid, int varid, int decompid, const size_t recnum,
-                            const unsigned char *op);
+                          const unsigned char *op);
     int nc_put_vard_ushort(int ncid, int varid, int decompid, const size_t recnum,
-                             const unsigned short *op);
+                           const unsigned short *op);
     int nc_put_vard_uint(int ncid, int varid, int decompid, const size_t recnum,
-                           const unsigned int *op);
+                         const unsigned int *op);
     int nc_put_vard_longlong(int ncid, int varid, int decompid, const size_t recnum,
-                               const long long *op);
+                             const long long *op);
     int nc_put_vard_ulonglong(int ncid, int varid, int decompid, const size_t recnum,
-                                const unsigned long long *op);
+                              const unsigned long long *op);
 
 #if defined(__cplusplus)
 }

diff --git a/src/clib/pio_file.c b/src/clib/pio_file.c
@@ -179,9 +179,10 @@ PIOc_createfile(int iosysid, int *ncidp, int *iotype, const char *filename,
  * parameters are read on comp task 0 and ignored elsewhere.
  *
  * @param iosysid : A defined pio system descriptor (input)
+ * @param path : The filename to create.
  * @param cmode : The netcdf mode for the create operation.
- * @param filename : The filename to open
  * @param ncidp : A pio file descriptor (output)
+ *
  * @return 0 for success, error code otherwise.
  * @ingroup PIO_create_file_c
  * @author Ed Hartnett

diff --git a/src/clib/pioc_support.c b/src/clib/pioc_support.c
@@ -1936,7 +1936,7 @@ PIOc_writemap_from_f90(const char *file, int ndims, const int *gdims,
  * PIO_IOTYPE_NETCDF4P.
  * @param filename The filename to create.
  * @param mode The netcdf mode for the create operation.
- * @paran use_ext_ncid non-zero to use an externally assigned ncid
+ * @param use_ext_ncid non-zero to use an externally assigned ncid
  * (used in the netcdf integration layer).
  *
  * @returns 0 for success, error code otherwise.
@@ -2422,7 +2422,7 @@ find_iotype_from_omode(int mode, int *iotype)
 /**
  * Find the appropriate IOTYPE from mode flags to nc_create().
  *
- * @param mode the mode flag from nc_create().
+ * @param cmode the mode flag from nc_create().
  * @param iotype pointer that gets the IOTYPE.
  *
  * @return 0 on success, error code otherwise.
@@ -2473,7 +2473,7 @@ find_iotype_from_cmode(int cmode, int *iotype)
  * @param mode the netcdf mode for the open operation
  * @param retry non-zero to automatically retry with netCDF serial
  * classic.
- * @paran use_ext_ncid non-zero to use an externally assigned ncid
+ * @param use_ext_ncid non-zero to use an externally assigned ncid
  * (used in the netcdf integration layer).
  *
  * @return 0 for success, error code otherwise.

diff --git a/src/flib/Makefile.am b/src/flib/Makefile.am
@@ -99,7 +99,7 @@ pionfput_mod.f90 pionfatt_mod_2.f90 pionfget_mod_2.f90
 piodarray.f90: piodarray.F90
 	$(CC) -E $< > $@
 piolib_mod.f90: piolib_mod.F90
-	$(CC) -E $< > $@
+	$(CC) -I../.. $(AM_CPPFLAGS) -E $< > $@
 pionfatt_mod.f90: pionfatt_mod.F90
 	$(CC) -E $< > $@
 pionfget_mod.f90: pionfget_mod.F90

diff --git a/src/flib/ncint_mod.F90 b/src/flib/ncint_mod.F90
@@ -14,17 +14,13 @@
 !!
 module ncint_mod
   use iso_c_binding
-  !--------------
   use pio_kinds
-  !--------------
   use pio_types, only : file_desc_t, iosystem_desc_t, var_desc_t, io_desc_t, &
        pio_iotype_netcdf, pio_iotype_pnetcdf, pio_iotype_netcdf4p, pio_iotype_netcdf4c, &
        pio_noerr, pio_rearr_subset, pio_rearr_opt_t
-  !--------------
   use pio_support, only : piodie, debug, debugio, debugasync, checkmpireturn
   use pio_nf, only : pio_set_log_level
   use piolib_mod, only : pio_init, pio_finalize
-  !
 
 #ifndef NO_MPIMOD
   use mpi    ! _EXTERNAL
@@ -35,7 +31,7 @@ module ncint_mod
   include 'mpif.h'    ! _EXTERNAL
 #endif
 
-  public :: nf_init_intracom, nf_free_iosystem
+  public :: nf_def_iosystem, nf_free_iosystem
 
 contains
 
@@ -61,7 +57,7 @@ module ncint_mod
   !! @param rearr_opts the rearranger options.
   !! @author Ed Hartnett
   !<
-  function nf_init_intracom(comp_rank, comp_comm, num_iotasks, &
+  function nf_def_iosystem(comp_rank, comp_comm, num_iotasks, &
        num_aggregator, stride,  rearr, iosystem, base, rearr_opts) result(ierr)
     use pio_types, only : pio_internal_error, pio_rearr_opt_t
     use iso_c_binding
@@ -90,7 +86,7 @@ end function nc_set_iosystem
 
     ierr = nc_set_iosystem(iosystem%iosysid)
 
-  end function nf_init_intracom
+  end function nf_def_iosystem
 
   !>
   !! @public

diff --git a/src/flib/pio.F90 b/src/flib/pio.F90
@@ -25,7 +25,7 @@ module pio
        pio_set_rearr_opts
 
 #ifdef NETCDF_INTEGRATION
-  use ncint_mod, only: nf_init_intracom, nf_free_iosystem
+  use ncint_mod, only: nf_def_iosystem, nf_free_iosystem
 #endif
 
   use pio_types, only : io_desc_t, file_desc_t, var_desc_t, iosystem_desc_t, &

diff --git a/src/ncint/ncint_pio.c b/src/ncint/ncint_pio.c
@@ -10,10 +10,11 @@
 #include <pio_internal.h>
 #include "ncintdispatch.h"
 
-/* The default io system id. */
+/** This is te default io system id. */
 extern int diosysid;
 
-/* Have we initialized? */
+/** Have we initialized the netCDF integration layer? This is where we
+ * register our dispatch layer with netcdf-c. */
 extern int ncint_initialized;
 
 /**
@@ -22,8 +23,8 @@ extern int ncint_initialized;
  * @author Ed Hartnett
  */
 int
-nc_init_intracomm(MPI_Comm comp_comm, int num_iotasks, int stride, int base, int rearr,
-                  int *iosysidp)
+nc_def_iosystemm(MPI_Comm comp_comm, int num_iotasks, int stride, int base,
+                 int rearr, int *iosysidp)
 {
     int ret;
 
@@ -92,10 +93,10 @@ nc_free_iosystem(int iosysid)
  * @author Ed Hartnett
  */
 int
-nc_init_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen,
+nc_def_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen,
                int maplen, const size_t *compmap, int *ioidp,
-               int rearranger, const size_t *iostart,
-               const size_t *iocount)
+              int rearranger, const size_t *iostart,
+              const size_t *iocount)
 {
     return PIOc_init_decomp(iosysid, pio_type, ndims, gdimlen, maplen,
                             (const PIO_Offset *)compmap, ioidp, rearranger,

diff --git a/src/ncint/ncintdispatch.h b/src/ncint/ncintdispatch.h
@@ -1,6 +1,7 @@
 /**
- * @file @internal This header file contains the prototypes for the
- * PIO netCDF integration layer.
+ * @file
+ * This header file contains the prototypes for the PIO netCDF
+ * integration layer.
  *
  * Ed Hartnett
  */
@@ -12,26 +13,6 @@
 #include <nc4dispatch.h>
 #include <netcdf_dispatch.h>
 
-/** This is the max size of an SD dataset name in HDF4 (from HDF4
- * documentation).*/
-#define NC_MAX_HDF4_NAME 64
-
-/** This is the max number of dimensions for a HDF4 SD dataset (from
- * HDF4 documentation). */
-#define NC_MAX_HDF4_DIMS 32
-
-/* Stuff below is for hdf4 files. */
-typedef struct NC_VAR_HDF4_INFO
-{
-    int sdsid;
-    int hdf4_data_type;
-} NC_VAR_HDF4_INFO_T;
-
-typedef struct NC_HDF4_FILE_INFO
-{
-    int sdid;
-} NC_HDF4_FILE_INFO_T;
-
 #if defined(__cplusplus)
 extern "C" {
 #endif

diff --git a/tests/fncint/ftst_pio.f90 b/tests/fncint/ftst_pio.f90
@@ -18,27 +18,37 @@ program ftst_pio
   type(io_desc_t) :: iodesc_nCells
   integer :: ierr
 
+  ! Set up MPI.
   call MPI_Init(ierr)
   call MPI_Comm_rank(MPI_COMM_WORLD, myRank, ierr)
   call MPI_Comm_size(MPI_COMM_WORLD, ntasks, ierr)
 
-
+  ! These control logging in the PIO and netCDF libraries.
   ierr = pio_set_log_level(2)
   ierr = nf_set_log_level(2)
-  ierr = nf_init_intracom(myRank, MPI_COMM_WORLD, niotasks, numAggregator, &
-       stride, PIO_rearr_subset, ioSystem, base)
 
+  ! Define an IOSystem.
+  ierr = nf_def_iosystem(myRank, MPI_COMM_WORLD, niotasks, numAggregator, &
+       stride, PIO_rearr_subset, ioSystem, base)
 
+  ! Define a decomposition.
   dims(1) = 3 * ntasks
   compdof = 3 * myRank + (/1, 2, 3/)  ! Where in the global array each task writes
-  data_buffer = myRank
   call PIO_initdecomp(ioSystem, PIO_int, dims, compdof, iodesc_nCells)
 
+  ! Create a file.
   ierr = nf_create(FILE_NAME, 64, ncid)
+
+  data_buffer = myRank
+
+  ! Close the file.
   ierr = nf_close(ncid)
 
+  ! Free resources.
   call PIO_freedecomp(ioSystem, iodesc_nCells)
   ierr = nf_free_iosystem()
+
+  ! We're done!
   call MPI_Finalize(ierr)
   if (myRank .eq. 0) then
      print *, '*** SUCCESS running ftst_pio!'