error handling in cvode (#382)

Co-authored-by: Daniel R. Reynolds <reynolds@smu.edu>

doc/cvode/guide/source/Introduction.rst

@@ -217,6 +217,12 @@ Users now need to link to ``sundials_core`` in addition to the libraries already
 This will be picked up automatically in projects that use the SUNDIALS CMake target. The library ``sundials_generic`` has been superceded by ``sundials_core`` and is no longer available.
 This fixes some duplicate symbol errors on Windows when linking to multiple SUNDIALS libraries.
 
+**Breaking change**
+The functions ``CVodeSetErrFile`` and ``CVodeSetHandlerErrFn`` have been removed.
+Users of these functions can use the functions :c:func:`SUNContext_PushErrHandler`,
+and :c:func:`SUNLogger_SetErrorFilename` instead. For further details see
+Sections :numref:`SUNDIALS.Errors` and :numref:`SUNDIALS.Logging`.
+
 Changes in v6.6.2
 -----------------
 

doc/cvode/guide/source/Usage/index.rst

@@ -807,12 +807,9 @@ error message to the error handler function. All error return values are
 negative, so the test ``flag < 0`` will catch all errors.
 
 The optional input calls can, unless otherwise noted, be executed in any order.
-However, if the user's program calls either :c:func:`CVodeSetErrFile` or
-:c:func:`CVodeSetErrHandlerFn`, then that call should appear first, in order to
-take effect for any later error message. Finally, a call to an ``CVodeSet***``
-function can, unless otherwise noted, be made at any time from the user's
-calling program and, if successful, takes effect immediately.
-
+A call to an ``CVodeSet***`` function can, unless otherwise noted, be made
+at any time from the user's calling program and, if successful, takes effect
+immediately.
 
 .. _CVODE.Usage.CC.optional_input.optin_main:
 
@@ -826,10 +823,6 @@ Main solver optional input functions
    +-------------------------------+---------------------------------------------+----------------+
    |      **Optional input**       |              **Function name**              |  **Default**   |
    +===============================+=============================================+================+
-   | Pointer to an error file      | :c:func:`CVodeSetErrFile`                   | ``stderr``     |
-   +-------------------------------+---------------------------------------------+----------------+
-   | Error handler function        | :c:func:`CVodeSetErrHandlerFn`              | internal fn.   |
-   +-------------------------------+---------------------------------------------+----------------+
    | User data                     | :c:func:`CVodeSetUserData`                  | ``NULL``       |
    +-------------------------------+---------------------------------------------+----------------+
    | Maximum order for BDF method  | :c:func:`CVodeSetMaxOrd`                    | 5              |
@@ -870,41 +863,6 @@ Main solver optional input functions
    +-------------------------------+---------------------------------------------+----------------+
 
 
-.. c:function:: int CVodeSetErrFile(void* cvode_mem, FILE * errfp)
-
-   The function ``CVodeSetErrFile`` specifies a pointer to the file  where all CVODE messages should be directed when the default  CVODE error handler function is used.
-
-   **Arguments:**
-     * ``cvode_mem`` -- pointer to the CVODE memory block.
-     * ``errfp`` -- pointer to output file.
-
-   **Return value:**
-     * ``CV_SUCCESS`` -- The optional value has been successfully set.
-     * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a previous call to :c:func:`CVodeCreate`.
-
-   **Notes:**
-      The default value for ``errfp`` is ``stderr``.  Passing a value of ``NULL`` disables all future error message output  (except for the case in which the CVODE memory pointer is ``NULL``).  This use of ``CVodeSetErrFile`` is strongly discouraged.
-
-      .. warning::
-
-        If ``CVodeSetErrFile`` is to be called, it should be called before any  other optional input functions, in order to take effect for any later error message.
-
-.. c:function:: int CVodeSetErrHandlerFn(void* cvode_mem, CVErrHandlerFn ehfun, void * eh_data)
-
-   The function ``CVodeSetErrHandlerFn`` specifies the optional user-defined function  to be used in handling error messages.
-
-   **Arguments:**
-     * ``cvode_mem`` -- pointer to the CVODE memory block.
-     * ``ehfun`` -- is the C error handler function of type :c:type:`CVErrHandlerFn`.
-     * ``eh_data`` -- pointer to user data passed to ``ehfun`` every time it is called.
-
-   **Return value:**
-     * ``CV_SUCCESS`` -- The function ``ehfun`` and data pointer ``eh_data`` have been successfully set.
-     * ``CV_MEM_NULL`` -- The CVODE memory block was not initialized through a previous call to :c:func:`CVodeCreate`.
-
-   **Notes:**
-      Error messages indicating that the CVODE solver memory is ``NULL`` will  always be directed to ``stderr``.
-
 .. c:function:: int CVodeSetUserData(void* cvode_mem, void * user_data)
 
    The function ``CVodeSetUserData`` specifies the user data block ``user_data``  and attaches it to the main CVODE memory block.
@@ -3342,35 +3300,6 @@ The user must provide a function of type defined as follows:
       equal to 1 (in which case CVODE returns ``CV_UNREC_RHSFUNC_ERR``).
 
 
-.. _CVODE.Usage.CC.user_fct_sim.ehFn:
-
-Error message handler function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As an alternative to the default behavior of directing error and warning
-messages to the file pointed to by ``errfp`` (see :c:func:`CVodeSetErrFile`), the user may provide a
-function of type ``CVErrHandlerFn`` to process any such messages. The function type
-:c:type:`CVErrHandlerFn` is defined as follows:
-
-.. c:type:: void (*CVErrHandlerFn)(int error_code, const char *module, const char *function, char *msg, void *eh_data);
-
-   This function processes error and warning message from CVODE and it sub-modules.
-
-   **Arguments:**
-      * ``error_code`` is the error code.
-      * ``module`` is the name of the CVODE module reporting the error.
-      * ``function`` is the name of the function in which the error occurred.
-      * ``msg`` is the error message.
-      * ``eh_data`` is a pointer to user data, the same as the ``eh_data`` parameter passed to :c:func:`CVodeSetErrHandlerFn`.
-
-   **Return value:**
-      * void
-
-   **Notes:**
-      ``error_code`` is negative for errors and positive (``CV_WARNING``) for warnings.
-      If a function that returns a pointer to memory encounters an error, it sets ``error_code`` to 0.
-
-
 .. _CVODE.Usage.CC.user_fct_sim.monitorfn:
 
 Monitor function

examples/cvode/parallel/cvAdvDiff_diag_p.c

@@ -44,9 +44,7 @@
 #include <nvector/nvector_parallel.h> /* access to MPI-parallel N_Vector     */
 #include <stdio.h>
 #include <stdlib.h>
-#include <sundials/sundials_logger.h>
-#include <sundials/sundials_mpi_errors.h>
-#include <sundials/sundials_types.h> /* definition of type realtype         */
+#include <sundials/sundials_core.h>
 
 /* Problem Constants */
 
@@ -131,11 +129,6 @@ int main(int argc, char* argv[])
   SUNContext_PushErrHandler(sunctx, SUNMPIAbortErrHandlerFn, NULL);
   SUNContext_PushErrHandler(sunctx, SUNLogErrHandlerFn, NULL);
 
-  /* Setup different error handler stack so that we abort after logging */
-  SUNContext_PopErrHandler(sunctx);
-  SUNContext_PushErrHandler(sunctx, SUNMPIAbortErrHandlerFn, NULL);
-  SUNContext_PushErrHandler(sunctx, SUNLogErrHandlerFn, NULL);
-
   /* This requires that SUNDIALS was configured with the CMake options
        SUNDIALS_LOGGING_LEVEL=n
     where n is one of:

include/cvode/cvode.h

@@ -94,9 +94,6 @@ typedef int (*CVRootFn)(sunrealtype t, N_Vector y, sunrealtype* gout,
 
 typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void* user_data);
 
-typedef void (*CVErrHandlerFn)(int error_code, const char* module,
-                               const char* function, char* msg, void* user_data);
-
 typedef int (*CVMonitorFn)(void* cvode_mem, void* user_data);
 
 /* -------------------
@@ -122,9 +119,6 @@ SUNDIALS_EXPORT int CVodeWFtolerances(void* cvode_mem, CVEwtFn efun);
 SUNDIALS_EXPORT int CVodeSetConstraints(void* cvode_mem, N_Vector constraints);
 SUNDIALS_EXPORT int CVodeSetDeltaGammaMaxLSetup(void* cvode_mem,
                                                 sunrealtype dgmax_lsetup);
-SUNDIALS_EXPORT int CVodeSetErrFile(void* cvode_mem, FILE* errfp);
-SUNDIALS_EXPORT int CVodeSetErrHandlerFn(void* cvode_mem, CVErrHandlerFn ehfun,
-                                         void* eh_data);
 SUNDIALS_EXPORT int CVodeSetInitStep(void* cvode_mem, sunrealtype hin);
 SUNDIALS_EXPORT int CVodeSetLSetupFrequency(void* cvode_mem, long int msbp);
 SUNDIALS_EXPORT int CVodeSetMaxConvFails(void* cvode_mem, int maxncf);

include/sundials/sundials_core.h

@@ -31,4 +31,8 @@
 #include <sundials/sundials_types.h>
 #include <sundials/sundials_version.h>
 
+#if SUNDIALS_MPI_ENABLED
+#include <sundials/sundials_mpi_errors.h>
+#endif
+
 #endif /* _SUNDIALS_CORE_H */