Merge pull request #612 from E3SM-Project/dqwu/fix_pio_set_buffer_size_limit

This PR fixes two major issues with the pio_set_buffer_size_limit
interface:

[Legacy Fortran library compatibility]
Update the legacy Fortran interface to include an optional second
argument to align with the newer interface used in E3SM/SCREAM,
resolving confirmed build errors.

[Allow 0 as a valid buffer size limit]
Update the handling of buffer size limit to allow 0 as a valid
value and also fix calls to PnetCDF API ncmpi_buffer_attach.

Fixes #611

Author: dqwu

ctest/CTestEnvironment-anlgce.cmake

@@ -126,3 +126,8 @@ if (DEFINED ENV{ENABLE_HDF5})
         endif ()
     endif ()
 endif ()
+
+# If USE_FORTRAN_LEGACY_LIB environment variable is set, then use the legacy Fortran library
+if (DEFINED ENV{USE_FORTRAN_LEGACY_LIB})
+    set (CTEST_CONFIGURE_OPTIONS "${CTEST_CONFIGURE_OPTIONS} -DPIO_USE_FORTRAN_LEGACY_LIB=ON")
+endif ()

src/clib/pio_darray.cpp

@@ -49,7 +49,7 @@ PIO_Offset PIOc_set_buffer_size_limit_impl(PIO_Offset limit)
     PIO_Offset oldsize = pio_buffer_size_limit;
 
     /* If the user passed a valid size, use it. */
-    if (limit > 0)
+    if (limit >= 0)
         pio_buffer_size_limit = limit;
 
     return oldsize;

src/clib/pioc_support.cpp

@@ -3411,7 +3411,18 @@ int spio_createfile_int(int iosysid, int *ncidp, const int *iotype, const char *
 
             ierr = ncmpi_create(ios->io_comm, filename, file->mode, ios->info, &file->fh);
             if (!ierr)
-                ierr = ncmpi_buffer_attach(file->fh, pio_buffer_size_limit);
+            {
+                /* When using buffered put APIs in PnetCDF, we must explicitly specify the size of the internal buffer.
+                   To avoid potential failures, we ensure a minimum buffer size (16 MiB) when pio_buffer_size_limit is
+                   0 or too small. If pio_buffer_size_limit is set to 0, this workaround prevents a direct failure of
+                   the ncmpi_buffer_attach call (NULL buffer error). Additionally, if pio_buffer_size_limit is too small,
+                   using the larger minimum size reduces the likelihood of potential NC_EINSUFFBUF errors. As recommended
+                   by PnetCDF documentation, users should make sure that the internal buffer size is sufficiently large
+                   for buffered put operations.
+                 */
+                const PIO_Offset min_bufsize = 16777216; /* Minimum buffer size (16 MiB) for buffered put APIs in PnetCDF */
+                ierr = ncmpi_buffer_attach(file->fh, (pio_buffer_size_limit > min_bufsize)? pio_buffer_size_limit : min_bufsize);
+            }
             break;
 #endif
 #ifdef _HDF5
@@ -4998,7 +5009,12 @@ int PIOc_openfile_retry_impl(int iosysid, int *ncidp, int *iotype, const char *f
             {
                 if (ios->iomaster == MPI_ROOT)
                     LOG((2, "%d Setting IO buffer %ld", __LINE__, pio_buffer_size_limit));
-                ierr = ncmpi_buffer_attach(file->fh, pio_buffer_size_limit);
+
+                /* Please refer to a previous related comment for why we ensure a minimum buffer size (16 MiB) for
+                   buffered put APIs in PnetCDF.
+                 */
+                const PIO_Offset min_bufsize = 16777216; /* Minimum buffer size (16 MiB) for buffered put APIs in PnetCDF */
+                ierr = ncmpi_buffer_attach(file->fh, (pio_buffer_size_limit > min_bufsize)? pio_buffer_size_limit : min_bufsize);
             }
             LOG((2, "ncmpi_open(%s) : fd = %d", filename, file->fh));
             break;

src/flib_legacy/piodarray.F90.in

@@ -93,8 +93,9 @@ end interface
 
 contains
 
-  subroutine pio_set_buffer_size_limit(limit)
+  subroutine pio_set_buffer_size_limit(limit, prev_limit)
     integer(PIO_OFFSET_KIND), intent(in) :: limit
+    integer(PIO_OFFSET_KIND), intent(out), optional :: prev_limit
     integer(PIO_OFFSET_KIND) :: oldval
     interface
        integer(C_LONG_LONG) function PIOc_set_buffer_size_limit(limit) &
@@ -103,10 +104,10 @@ contains
          integer(C_LONG_LONG), value :: limit
        end function PIOc_set_buffer_size_limit
     end interface
-    if(limit<0) then
-       call piodie(__PIO_FILE__,__LINE__,' bad value to buffer_size_limit: ',int(limit))
-    end if
     oldval = PIOc_set_buffer_size_limit(limit)
+    if(present(prev_limit)) then
+       prev_limit = oldval
+    end if
 
   end subroutine pio_set_buffer_size_limit
 

tests/general/pio_buf_lim_tests.F90.in

@@ -33,6 +33,8 @@ PIO_TF_AUTO_TEST_SUB_BEGIN nc_wr_buf_limit_zero
   implicit none
   integer, parameter :: VEC_LOCAL_SZ = 7
   integer(kind=pio_offset_kind), parameter :: PIO_BUFFER_SZ_ZERO = 0
+  integer(kind=pio_offset_kind), parameter :: PIO_BUFFER_SZ_NEG = -1
+  integer(kind=pio_offset_kind) :: cur_buf_sz_limit
   type(var_desc_t)  :: pio_var
   type(file_desc_t) :: pio_file
   character(len=PIO_TF_MAX_STR_LEN) :: filename
@@ -76,6 +78,11 @@ PIO_TF_AUTO_TEST_SUB_BEGIN nc_wr_buf_limit_zero
 
     call pio_set_buffer_size_limit(PIO_BUFFER_SZ_ZERO)
 
+    ! Query the current buffer size limit by passing a negative value for the
+    ! new limit, which will be ignored by pio_set_buffer_size_limit
+    call pio_set_buffer_size_limit(PIO_BUFFER_SZ_NEG, prev_limit=cur_buf_sz_limit)
+    PIO_TF_PASSERT(cur_buf_sz_limit == PIO_BUFFER_SZ_ZERO, "Current buffer size limit should equal the previously set zero limit")
+
     ! Write the variable out
     call PIO_write_darray(pio_file, pio_var, iodesc, wbuf, ierr)
     PIO_TF_CHECK_ERR(ierr, "Failed to write darray : " // trim(filename))