Deprecate MPI without MPI I/O

doc/mainpage.dox

@@ -55,7 +55,9 @@
  *                    compiler wrappers.  If this option is not given, wrappers
  *                    for MPI routines are used instead and the code is compiled
  *                    in serial only.
- * * `--disable-mpiio`  may be used to avoid using `MPI_File` based calls.
+ * * `--disable-mpiio`  may be used to avoid using `MPI_File` based calls. The
+                      usage of `--disable-mpiio` is deprecated and should not be
+                      used anymore.
  *
  * A typical development configure line looks as follows:
  * > `relative/path/to/configure CFLAGS="-Wall -O0 -g" --enable-mpi --enable-debug`

doc/release_notes.txt

@@ -34,9 +34,12 @@ There have been breaking changes, very strictly speaking.
 
 ### Functionality
 
- - Further align I/O wrappers with and without MPI I/O.
+ - Further align I/O wrappers with and without MPI.
+ - Change the semantic of sc_io_open to always truncate a newly created file.
  - Simplify the replacements for MPI_{read,write}_at*.
  - Further updates to the MPI I/O wrapper code.
+ - Deprecate the configuration with MPI but without MPI I/O.
+ - Remove sc_io_{write,read}_all.
  - Add sc_io_source, sink_destroy_null functions.
  - Make sure not to sc_io_source_read an array beyond its length.
  - Add sc_io_file_load, save functions and test program.

src/sc3_mpi_types.h

@@ -120,6 +120,9 @@ typedef MPI_Op      sc3_MPI_Op_t;
 typedef enum sc3_MPI_IO_Errorcode
 {
   /* only MPI I/O error classes */
+  /* WARNING: This enum is only used in the deprecated case of activated MPI but
+   * deactivated MPI I/O.
+   */
   SC3_MPI_ERR_FILE = MPI_ERR_LASTCODE,
   SC3_MPI_ERR_NOT_SAME,
   SC3_MPI_ERR_AMODE,
@@ -197,7 +200,6 @@ sc3_MPI_Op_t;
 /** We wrap some MPI error codes and the I/O error classes. */
 typedef enum sc3_MPI_Errorcode
 {
-  /* we separate the error values from errno values */
   SC3_MPI_SUCCESS = 0,  /**< An MPI function has exited successfully. */
   SC3_MPI_ERR_ARG = 14000, /**< An MPI function encountered invalid arguments. */
   SC3_MPI_ERR_COUNT,     /**< An MPI function encountered an invalid count argument. */

src/sc_io.c

@@ -1640,6 +1640,7 @@ sc_io_open (sc_MPI_Comm mpicomm, const char *filename,
 
   return errcode;
 #else
+  /* WARNING: This code with activated MPI (SC_ENABLE_MPI) is deprecated. */
   /* allocate internal file context */
   *mpifile = (sc_MPI_File) SC_ALLOC (struct sc_no_mpiio_file, 1);
   (*mpifile)->filename = filename;
@@ -1702,16 +1703,6 @@ sc_io_read (sc_MPI_File mpifile, void *ptr, size_t zcount,
 #endif
 }
 
-int
-sc_io_read_at_legal (void)
-{
-#ifdef SC_ENABLE_MPIIO
-  return 1;
-#else
-  return 0;
-#endif
-}
-
 int
 sc_io_read_at (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr,
                int count, sc_MPI_Datatype t, int *ocount)
@@ -1740,6 +1731,8 @@ sc_io_read_at (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr,
   return errcode;
 #else
 
+  /* WARNING: This code with activated MPI (SC_ENABLE_MPI) is deprecated. */
+
   /* The value count > 0 is only legal on rank 0.
    * On all other ranks the code is only legal for count == 0.
    */
@@ -1823,6 +1816,9 @@ sc_io_read_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr,
   return errcode;
 #elif defined SC_ENABLE_MPI
   /* MPI but no MPI IO */
+
+  /* WARNING: This code and configuration case is deprecated. */
+
   {
     int                 mpisize, rank, count, size;
     int                 active, errval;
@@ -1965,13 +1961,6 @@ sc_io_read_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, void *ptr,
 #endif
 }
 
-int
-sc_io_read_all (sc_MPI_File mpifile, void *ptr, int count, sc_MPI_Datatype t,
-                int *ocount)
-{
-  return sc_io_read_at_all (mpifile, 0, ptr, count, t, ocount);
-}
-
 void
 sc_io_write (sc_MPI_File mpifile, const void *ptr, size_t zcount,
              sc_MPI_Datatype t, const char *errmsg)
@@ -1998,12 +1987,6 @@ sc_io_write (sc_MPI_File mpifile, const void *ptr, size_t zcount,
 #endif
 }
 
-int
-sc_io_write_at_legal (void)
-{
-  return sc_io_read_at_legal ();
-}
-
 int
 sc_io_write_at (sc_MPI_File mpifile, sc_MPI_Offset offset,
                 const void *ptr, int count, sc_MPI_Datatype t,
@@ -2033,6 +2016,8 @@ sc_io_write_at (sc_MPI_File mpifile, sc_MPI_Offset offset,
   return errcode;
 #else
 
+  /* WARNING: This code with activated MPI (SC_ENABLE_MPI) is deprecated. */
+
   /* The value count > 0 is only legal on rank 0.
    * On all other ranks the code is only legal for count == 0.
    */
@@ -2116,6 +2101,9 @@ sc_io_write_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset,
   return errcode;
 #elif defined SC_ENABLE_MPI
   /* MPI but no MPI IO */
+
+  /* WARNING: This code and configuration case is deprecated. */
+
   /* offset is ignored and we use here the append mode.
    * This is the case since the C-standard open mode
    * "wb" would earse the existing file and create a
@@ -2262,13 +2250,6 @@ sc_io_write_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset,
 #endif
 }
 
-int
-sc_io_write_all (sc_MPI_File mpifile, const void *ptr, int count,
-                 sc_MPI_Datatype t, int *ocount)
-{
-  return sc_io_write_at_all (mpifile, 0, ptr, count, t, ocount);
-}
-
 int
 sc_io_close (sc_MPI_File * mpifile)
 {
@@ -2282,6 +2263,9 @@ sc_io_close (sc_MPI_File * mpifile)
   mpiret = sc_io_error_class (mpiret, &eclass);
   SC_CHECK_MPI (mpiret);
 #else
+
+  /* WARNING: This code with activated MPI (SC_ENABLE_MPI) is deprecated. */
+
   int                 retval;
 
   eclass = sc_MPI_SUCCESS;

src/sc_io.h

@@ -32,7 +32,7 @@
  *    provide functions centered around \ref sc_io_sink_new and \ref
  *    sc_io_source_new.
  *  - To abstract parallel file I/O in a way that works both with and
- *    without MPI I/O support, we provide \ref sc_io_open, \ref sc_io_write
+ *    without MPI support, we provide \ref sc_io_open, \ref sc_io_write
  *    and friends.
  *  - To write to the VTK binary compressed format, we provide suitable
  *    functions to base64 encode and zlib-compress as required; see
@@ -44,22 +44,6 @@
  *    and base64-encoded format and back that is unambiguously defined and
  *    human-friendly.
  *
- * \note For the function \ref sc_io_write_at_all without MPI IO but with MPI
- *       the \b offset argument is ignored. In this case the function writes at
- *       the current end of the file. Hereby, the MPI ranks write in the
- *       rank-induced order. That is why the function may work equivalent to
- *       the MPI IO and non-MPI case but it can not be guaranteed.
- *       Furthermore, it is important to notice that \ref sc_io_write_at and
- *       \ref sc_io_read_at are only valid to call with zcount > 0 on rank 0,
- *       if MPI IO is not available. During runtime this can be checked by the
- *       user by calling \ref sc_io_read_at_legal and \ref sc_io_write_at_legal,
- *       respectively.
- *       The recommended way of reading/writing with multiple ranks with
- *       zcount > 0 if \ref sc_io_read_at_legal / \ref sc_io_write_at_legal
- *       returns 0 is to use \ref sc_io_read_at_all / \ref sc_io_write_at_all
- *       with the whished zcount on the ranks whished by the user and set zcount
- *       to 0 on the remaining ranks. 
- *
  * \ingroup io
  */
 
@@ -582,14 +566,15 @@ void                sc_fread (void *ptr, size_t size,
  */
 void                sc_fflush_fsync_fclose (FILE * file);
 
-/** Opens a MPI file or without MPI I/O or even without MPI a file context.
+/** Opens a MPI file or without MPI a file context.
+ *
  * \param[in] mpicomm   MPI communicator
  * \param[in] filename  The path to the file that we want to open.
  * \param[in] amode     An access mode.
  * \param[in] mpiinfo   The MPI info
  * \param[out] mpifile  The MPI file that is opened. This can be a
  *                      an actual MPI IO file or an internal file
- *                      conntext to preserve some MPI IO functionalities
+ *                      conntext to preserve some IO functionalities
  *                      without MPI IO and to have working code without
  *                      MPI at all. This output variable is only filled if the
  *                      return value of the function is \ref sc_MPI_SUCCESS.
@@ -623,23 +608,10 @@ void                sc_io_read (sc_MPI_File mpifile, void *ptr,
                                 size_t zcount, sc_MPI_Datatype t,
                                 const char *errmsg);
 
-/** Check for restricted usage of \ref sc_io_read_at.
- *
- * \return              0 if the restriction described in the note of \ref
- *                      sc_io_read_at applies, i.e. count > 0 is only legal
- *                      on rank 0. This is equivalent to MPI I/O being not
- *                      available.
- *                      Otherwise, the function returns 1, i.e. MPI I/O is
- *                      available and the restriction in the note of \ref
- *                      sc_io_read_at does not apply, i.e. the user can pass
- *                      any valid count on any valid rank.
- *
- */
-int                 sc_io_read_at_legal (void);
-
 /** Read MPI file content into memory for an explicit offset.
  * This function does not update the file pointer of the MPI file.
  * Contrary to \ref sc_io_read, it does not abort on read errors.
+ *
  * \param [in,out] mpifile      MPI file object opened for reading.
  * \param [in] offset   Starting offset in counts of the type \b t.
  * \param [in] ptr      Data array to read from disk.
@@ -649,11 +621,6 @@ int                 sc_io_read_at_legal (void);
  * \return              A sc_MPI_ERR_* as defined in \ref sc_mpi.h.
  *                      The error code can be passed to
  *                      \ref sc_MPI_Error_string.
- * \note                If MPI I/O is not available this function has restricted
- *                      functionality in the sense that for \b count > 0, this
- *                      function is only legal to call on rank 0. On all other
- *                      ranks \b count must be 0. If this requirement is
- *                      violated this function returns \ref sc_MPI_ERR_ARG.
  */
 int                 sc_io_read_at (sc_MPI_File mpifile,
                                    sc_MPI_Offset offset, void *ptr,
@@ -662,6 +629,7 @@ int                 sc_io_read_at (sc_MPI_File mpifile,
 
 /** Read MPI file content collectively into memory for an explicit offset.
  * This function does not update the file pointer of the MPI file.
+ *
  * \param [in,out] mpifile      MPI file object opened for reading.
  * \param [in] offset   Starting offset in counts of the type \b t.
  * \param [in] ptr      Data array to read from disk.
@@ -677,24 +645,6 @@ int                 sc_io_read_at_all (sc_MPI_File mpifile,
                                        int count, sc_MPI_Datatype t,
                                        int *ocount);
 
-/** Read memory content collectively from an MPI file.
- * A call of this function is equivalent to call \ref sc_io_read_at_all
- * with offset = 0 but the call of this function is not equivalent
- * to a call of MPI_File_read_all since this function ignores the current
- * position of the file cursor.
- * \param [in,out] mpifile      MPI file object opened for reading.
- * \param [in] ptr      Data array to read from disk.
- * \param [in] count    Number of array members.
- * \param [in] t        The MPI type for each array member.
- * \param [out] ocount  The number of read elements of type \b t.
- * \return              A sc_MPI_ERR_* as defined in \ref sc_mpi.h.
- *                      The error code can be passed to
- *                      \ref sc_MPI_Error_string.
- */
-int                 sc_io_read_all (sc_MPI_File mpifile, void *ptr,
-                                    int count, sc_MPI_Datatype t,
-                                    int *ocount);
-
 #define sc_mpi_write        sc_io_write  /**< For backwards compatibility. */
 
 /** Write memory content to an MPI file.
@@ -713,23 +663,10 @@ void                sc_io_write (sc_MPI_File mpifile, const void *ptr,
                                  size_t zcount, sc_MPI_Datatype t,
                                  const char *errmsg);
 
-/** Check for restricted usage of \ref sc_io_write_at.
- *
- * \return              0 if the restriction described in the note of \ref
- *                      sc_io_write_at applies, i.e. count > 0 is only legal
- *                      on rank 0. This is equivalent to MPI I/O being not
- *                      available.
- *                      Otherwise, the function returns 1, i.e. MPI I/O is
- *                      available and the restriction in the note of \ref
- *                      sc_io_write_at does not apply, i.e. the user can pass
- *                      any valid count on any valid rank.
- *
- */
-int                 sc_io_write_at_legal (void);
-
 /** Write MPI file content into memory for an explicit offset.
  * This function does not update the file pointer that is part of mpifile.
- * Contrary to \ref sc_io_write, it does not abort on read errors. 
+ * Contrary to \ref sc_io_write, it does not abort on read errors.
+ *
  * \param [in,out] mpifile      MPI file object opened for reading.
  * \param [in] offset   Starting offset in etype, where the etype is given by
  *                      the type t.
@@ -740,11 +677,6 @@ int                 sc_io_write_at_legal (void);
  * \return              A sc_MPI_ERR_* as defined in \ref sc_mpi.h.
  *                      The error code can be passed to
  *                      \ref sc_MPI_Error_string.
- * \note                If MPI I/O is not available this function has restricted
- *                      functionality in the sense that for \b count > 0, this
- *                      function is only legal to call on rank 0. On all other
- *                      ranks \b count must be 0. If this requirement is
- *                      violated this function returns \ref sc_MPI_ERR_ARG.
  */
 int                 sc_io_write_at (sc_MPI_File mpifile,
                                     sc_MPI_Offset offset,
@@ -754,15 +686,9 @@ int                 sc_io_write_at (sc_MPI_File mpifile,
 /** Write MPI file content collectively into memory for an explicit offset.
  * This function does not update the file pointer that is part of mpifile.
  *
- * \note  If there is no MPI IO but MPI available, the offset parameter is
- *        ignored and the ranks just write at the current end of the file
- *        according to their rank-induced order.
  * \param [in,out] mpifile      MPI file object opened for reading.
  * \param [in] offset   Starting offset in etype, where the etype is given by
- *                      the type t. This parameter is ignored in the case of
- *                      having MPI but no MPI IO. In this case this function
- *                      writes to the current end of the file as described
- *                      above.
+ *                      the type t.
  * \param [in] ptr      Data array to write to disk.
  * \param [in] count    Number of array members.
  * \param [in] t        The MPI type for each array member.
@@ -776,25 +702,8 @@ int                 sc_io_write_at_all (sc_MPI_File mpifile,
                                         const void *ptr, int count,
                                         sc_MPI_Datatype t, int *ocount);
 
-/** Write memory content collectively to an MPI file.
- * A call of this function is equivalent to call \ref sc_io_write_at_all
- * with offset = 0 but the call of this function is not equivalent
- * to a call of MPI_File_write_all since this function ignores the current
- * position of the file cursor.
- * \param [in,out] mpifile      MPI file object opened for writing.
- * \param [in] ptr      Data array to write to disk.
- * \param [in] count    Number of array members.
- * \param [in] t        The MPI type for each array member.
- * \param [out] ocount  The number of written elements of type \b t.
- * \return              A sc_MPI_ERR_* as defined in \ref sc_mpi.h.
- *                      The error code can be passed to
- *                      \ref sc_MPI_Error_string.
- */
-int                 sc_io_write_all (sc_MPI_File mpifile,
-                                     const void *ptr, int count,
-                                     sc_MPI_Datatype t, int *ocount);
-
 /** Close collectively a sc_MPI_File.
+ *
  * \param[in] file  MPI file object that is closed.
  * \return              A sc_MPI_ERR_* as defined in \ref sc_mpi.h.
  *                      The error code can be passed to

src/sc_mpi.h

@@ -139,6 +139,9 @@ sc_tag_t;
 typedef enum sc_MPI_IO_Errorcode
 {
   /* only MPI I/O error classes */
+  /* WARNING: This enum is only used in the deprecated case of activated MPI but
+   * deactivated MPI I/O.
+   */
   sc_MPI_ERR_FILE = MPI_ERR_LASTCODE,
   sc_MPI_ERR_NOT_SAME,
   sc_MPI_ERR_AMODE,