error handling in kinsol

doc/kinsol/guide/source/Introduction.rst

@@ -187,6 +187,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 ``KINSetErrFile`` and ``KINSetHandlerErrFn`` 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/kinsol/guide/source/Usage/index.rst

@@ -458,10 +458,6 @@ negative, so a test ``retval`` :math:`<0` will catch any error.
   +========================================================+==================================+==============================+
   | **KINSOL main solver**                                 |                                  |                              |
   +--------------------------------------------------------+----------------------------------+------------------------------+
-  | Error handler function                                 | :c:func:`KINSetErrHandlerFn`     | internal fn.                 |
-  +--------------------------------------------------------+----------------------------------+------------------------------+
-  | Pointer to an error file                               | :c:func:`KINSetErrFile`          | ``stderr``                   |
-  +--------------------------------------------------------+----------------------------------+------------------------------+
   | Info handler function                                  | :c:func:`KINSetInfoHandlerFn`    | internal fn.                 |
   +--------------------------------------------------------+----------------------------------+------------------------------+
   | Data for problem-defining function                     | :c:func:`KINSetUserData`         | ``NULL``                     |
@@ -527,57 +523,6 @@ negative, so a test ``retval`` :math:`<0` will catch any error.
   +--------------------------------------------------------+----------------------------------+------------------------------+
 
 
-.. c:function:: int KINSetErrFile(void * kin_mem, FILE * errfp)
-
-   The function :c:func:`KINSetErrFile` specifies the pointer to the file  where
-   all KINSOL messages should be directed when the default  KINSOL error handler
-   function is used.
-
-   **Arguments:**
-     * ``kin_mem`` -- pointer to the KINSOL memory block.
-     * ``errfp`` -- pointer to output file.
-
-   **Return value:**
-     * ``KIN_SUCCESS`` -- The optional value has been successfully set.
-     * ``KIN_MEM_NULL`` -- The ``kin_mem`` pointer is ``NULL``.
-
-   **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 KINSOL memory pointer is ``NULL``).  This use of
-      :c:func:`KINSetErrFile` is strongly discouraged.
-
-   .. warning::
-      If :c:func:`KINSetErrFile` 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 KINSetErrHandlerFn(void * kin_mem, KINErrHandlerFn ehfun, void * eh_data)
-
-   The function :c:func:`KINSetErrHandlerFn` specifies the optional user-defined
-   function  to be used in handling error messages.
-
-   **Arguments:**
-     * ``kin_mem`` -- pointer to the KINSOL memory block.
-     * ``ehfun`` -- is the user's CC error handler function (see :numref:`KINSOL.Usage.CC.user_fct_sim.ehFn`).
-     * ``eh_data`` -- pointer to user data passed to ``ehfun`` every time it is called.
-
-   **Return value:**
-     * ``KIN_SUCCESS`` -- The function ``ehfun`` and data pointer ``eh_data`` have been successfully set.
-     * ``KIN_MEM_NULL`` -- The ``kin_mem`` pointer is ``NULL``.
-
-   **Notes:**
-      The default internal error handler function directs error messages to the
-      file specified by the file pointer ``errfp`` (see :c:func:`KINSetErrFile`
-      above).
-
-      Error messages indicating that the KINSOL solver memory is
-      ``NULL`` will  always be directed to ``stderr``.
-
-
 .. c:function:: int KINSetUserData(void * kin_mem, void * user_data)
 
    The function :c:func:`KINSetUserData` specifies the pointer to user-defined
@@ -1869,38 +1814,6 @@ The user must provide a function of type :c:type:`KINSysFn` defined as follows:
       Allocation of memory for ``fval`` is handled within KINSOL.
 
 
-.. _KINSOL.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:`KINSetErrFile`), the
-user may provide a function of type :c:type:`KINErrHandlerFn` to process any
-such messages.  The function type :c:type:`KINErrHandlerFn` is defined as
-follows:
-
-.. c:type:: void (*KINErrHandlerFn)(int error_code, const char *module, const char *function, char *msg, void *user_data)
-
-   This function processes error and warning messages from KINSOL and its
-   sub-modules.
-
-   **Arguments:**
-      * ``error_code`` -- is the error code
-      * ``module`` -- is the name of the KINSOL module reporting the error
-      * ``function`` -- is the name of the function in which the error occurred
-      * ``eH_data`` -- is a pointer to user data, the same as the ``eh_data``
-        parameter passed to :c:func:`KINSetErrHandlerFn`
-
-   **Return value:**
-      This function has no return value.
-
-   **Notes:**
-      ``error_code`` is negative for errors and positive (``KIN_WARNING``) for
-      warnings. If a function that returns a pointer to memory encounters an error,
-      it sets ``error_code`` to 0.
-
-
 .. _KINSOL.Usage.CC.user_fct_sim.jacFn:
 
 Jacobian construction (matrix-based linear solvers)

include/kinsol/kinsol.h

@@ -82,9 +82,6 @@ extern "C" {
 
 typedef int (*KINSysFn)(N_Vector uu, N_Vector fval, void* user_data);
 
-typedef void (*KINErrHandlerFn)(int error_code, const char* module,
-                                const char* function, char* msg, void* user_data);
-
 typedef void (*KINInfoHandlerFn)(const char* module, const char* function,
                                  char* msg, void* user_data);
 
@@ -131,11 +128,6 @@ SUNDIALS_EXPORT int KINSetScaledStepTol(void* kinmem, sunrealtype scsteptol);
 SUNDIALS_EXPORT int KINSetConstraints(void* kinmem, N_Vector constraints);
 SUNDIALS_EXPORT int KINSetSysFunc(void* kinmem, KINSysFn func);
 
-/* Optional input functions for handling error events */
-SUNDIALS_EXPORT int KINSetErrHandlerFn(void* kinmem, KINErrHandlerFn ehfun,
-                                       void* eh_data);
-SUNDIALS_EXPORT int KINSetErrFile(void* kinmem, FILE* errfp);
-
 /* Optional output functions */
 SUNDIALS_EXPORT int KINGetWorkSpace(void* kinmem, long int* lenrw,
                                     long int* leniw);

src/kinsol/fmod/fkinsol_mod.c

@@ -637,36 +637,6 @@ SWIGEXPORT int _wrap_FKINSetSysFunc(void *farg1, KINSysFn farg2) {
 }
 
 
-SWIGEXPORT int _wrap_FKINSetErrHandlerFn(void *farg1, KINErrHandlerFn farg2, void *farg3) {
-  int fresult ;
-  void *arg1 = (void *) 0 ;
-  KINErrHandlerFn arg2 = (KINErrHandlerFn) 0 ;
-  void *arg3 = (void *) 0 ;
-  int result;
-
-  arg1 = (void *)(farg1);
-  arg2 = (KINErrHandlerFn)(farg2);
-  arg3 = (void *)(farg3);
-  result = (int)KINSetErrHandlerFn(arg1,arg2,arg3);
-  fresult = (int)(result);
-  return fresult;
-}
-
-
-SWIGEXPORT int _wrap_FKINSetErrFile(void *farg1, void *farg2) {
-  int fresult ;
-  void *arg1 = (void *) 0 ;
-  FILE *arg2 = (FILE *) 0 ;
-  int result;
-
-  arg1 = (void *)(farg1);
-  arg2 = (FILE *)(farg2);
-  result = (int)KINSetErrFile(arg1,arg2);
-  fresult = (int)(result);
-  return fresult;
-}
-
-
 SWIGEXPORT int _wrap_FKINGetWorkSpace(void *farg1, long *farg2, long *farg3) {
   int fresult ;
   void *arg1 = (void *) 0 ;

src/kinsol/fmod/fkinsol_mod.f90

@@ -99,8 +99,6 @@ module fkinsol_mod
  public :: FKINSetScaledStepTol
  public :: FKINSetConstraints
  public :: FKINSetSysFunc
- public :: FKINSetErrHandlerFn
- public :: FKINSetErrFile
  public :: FKINGetWorkSpace
  public :: FKINGetNumNonlinSolvIters
  public :: FKINGetNumFuncEvals
@@ -408,25 +406,6 @@ function swigc_FKINSetSysFunc(farg1, farg2) &
 integer(C_INT) :: fresult
 end function
 
-function swigc_FKINSetErrHandlerFn(farg1, farg2, farg3) &
-bind(C, name="_wrap_FKINSetErrHandlerFn") &
-result(fresult)
-use, intrinsic :: ISO_C_BINDING
-type(C_PTR), value :: farg1
-type(C_FUNPTR), value :: farg2
-type(C_PTR), value :: farg3
-integer(C_INT) :: fresult
-end function
-
-function swigc_FKINSetErrFile(farg1, farg2) &
-bind(C, name="_wrap_FKINSetErrFile") &
-result(fresult)
-use, intrinsic :: ISO_C_BINDING
-type(C_PTR), value :: farg1
-type(C_PTR), value :: farg2
-integer(C_INT) :: fresult
-end function
-
 function swigc_FKINGetWorkSpace(farg1, farg2, farg3) &
 bind(C, name="_wrap_FKINGetWorkSpace") &
 result(fresult)
@@ -1189,41 +1168,6 @@ function FKINSetSysFunc(kinmem, func) &
 swig_result = fresult
 end function
 
-function FKINSetErrHandlerFn(kinmem, ehfun, eh_data) &
-result(swig_result)
-use, intrinsic :: ISO_C_BINDING
-integer(C_INT) :: swig_result
-type(C_PTR) :: kinmem
-type(C_FUNPTR), intent(in), value :: ehfun
-type(C_PTR) :: eh_data
-integer(C_INT) :: fresult 
-type(C_PTR) :: farg1 
-type(C_FUNPTR) :: farg2 
-type(C_PTR) :: farg3 
-
-farg1 = kinmem
-farg2 = ehfun
-farg3 = eh_data
-fresult = swigc_FKINSetErrHandlerFn(farg1, farg2, farg3)
-swig_result = fresult
-end function
-
-function FKINSetErrFile(kinmem, errfp) &
-result(swig_result)
-use, intrinsic :: ISO_C_BINDING
-integer(C_INT) :: swig_result
-type(C_PTR) :: kinmem
-type(C_PTR) :: errfp
-integer(C_INT) :: fresult 
-type(C_PTR) :: farg1 
-type(C_PTR) :: farg2 
-
-farg1 = kinmem
-farg2 = errfp
-fresult = swigc_FKINSetErrFile(farg1, farg2)
-swig_result = fresult
-end function
-
 function FKINGetWorkSpace(kinmem, lenrw, leniw) &
 result(swig_result)
 use, intrinsic :: ISO_C_BINDING