Standard library error reporting

[wclodius2]

Currently my default approach to dealing with errors is to have an
optional status flag for the procedure in which the error is found,
one or more routines for writing an error message, and a branch for
either setting the status flag or reporting the error while stopping
processing, e.g., the psuedo code

subroutine example(..., status )
    ...
    integer, intent(out), optional :: status
    ...
    if (present(status)) status = success ! Set default value
    ...
    if (bad stuff is found) go to label
    ...
! Error handling is placed at the end of the routine
label if (present status) then
        status = bad_stuff_flag
	    return
    else
        call report_error_and_stop(...)
    end if
    ...
end subroutine example

I want to write some code for the Standard Library that will have to
handle errors. This prompts the following questions:

1. Is this a good approach for handling errors in the Standard Library
   given the limitations of Fortran?

2. If this is not a good approach what is a better approach?

3. If this is a good approach should the Standard Library have a
   module supporting this approach?

4. If it should have a module what should be the API of that module?

In thinking about the API I have been looking at the error handling of
Futility and its inspiration FLIBS. My examination so far has been
superficial. My current approach is to send all information to the
STD_ERR of ISO_FORTRAN_ENV. Futility and FLIBS send it to a log
file. Futility has an object based system that allows it to send
messages to multiple log files. This prompts the following questions:

1. Is supporting a log file separate from STD_ERR useful?

2. If it is useful should a log file be required or should the default
   be STD_ERR?

3. Would more than one log file be useful?

4. Should there be an option to report to both the log file and
   STD_ERR?

Futility and FLIBS also focus on the severity of the error, providing
five levels of error reporting: INFORMATION, WARNING, ERROR, FATAL
ERROR, and FAILURE. I have tended to have just WARNING and the
equivalent of FATAL ERROR. Are multiple levels of error that useful?

I have focussed on reporting the location where the error was
discovered, providing optional MODULE and PROCEDURE arguments for
reporting the MODULE and PROCEDURE in which the call was made> Would
others find that useful? If the error is discovered in an internal
procedure of a module procedure would an optional INTERNAL_PROCEDURE
argument be useful?

I have also focussed on enumerating various sources of errors, e.g.,
ALLOC_FAULT, CONSISTENCY_FAULT, CONVERGENCE_FAILURE,
MISSING_FILE, etc., to provide a consistent nomenclature for the
STATUS flags and an informative string for the ERROR STOP
code. Would other people find such an enumeration useful? If it is useful
is the enumeration best as a simple INTEGER or as a derived type, say
ERRORS?

[certik]

Error handling is something that we were not able to reach an agreement what the best approach is as a community yet.

We have discussed this several times in issues (I don't have time right now to look them up).

In general, if you are writing new code that requires error handling, then I would recommend to discuss the API of that code, and see if we can agree what error handling would best make sense for that code.

As an example, if you are writing a find function for strings, then the best error handling might be to simply return -1 if the given substring cannot be found, as in Python. If you are writing something else, then other error handling mechanisms might be more appropriate.

[milancurcic]

This seems related to #193.

[jvdp1]

This seems related to #193.

This is also related to #95.

This issue seems to come back quite often. How can we move forward and fix it ? :)
The approaches of the propositions of the different issues #95, #193 ,#219 seem to be also all similar.