Efficient and easy to use error handling for modern Fortran.
Fortran does not have any built-in mechanisms for errors as seen in most other programming languages. Over the years, developers often have resorted to integer or logical arguments as error flags and manual labelling of error returns to be able to determine the source of the error. This process is time consuming and mistakes lead to inaccurate information and annoyance while debugging.
The error-handling library provides a solution for error handling in Fortran code. It is primarily targeted towards development of Fortran based applications, but could be used in library code as well.
At its core is the abstract type error_t which is used to indicate if a procedure
invocation has failed.
Errors can be handled gracefully and context can be added while returning up
the call stack.
It is also possible to make code where errors can be identified and handled programmatically
by extending the error_t base class.
But perhaps most interesting is the ability to generate stacktraces along with any error when combined with the fortran-stacktrace library. This means that you can easily make even old legacy code output errors messages like this:
The source code snippets are of course voluntary and only available on a machine with access to the source code itself.
All functionality is located in the error_handling module.
When writing a subroutine that might fail, add an class(error_t), allocatable argument.
Use the fail function to create a general error with a given message, for example:
module sqrt_inplace_mod
use error_handling, only: error_t, fail
implicit none
private
public sqrt_inplace
contains
pure subroutine sqrt_inplace(x, error)
real, intent(inout) :: x
class(error_t), allocatable, intent(inout) :: error
if (x <= 0.0) then
error = fail('x is negative')
return
end if
x = sqrt(x)
end subroutine
end module|
Note
|
If the subroutine is pure or elemental the intent must be intent(inout) in order
to be standard compliant, otherwise intent(out) may be used.
|
Then use your newly created routines:
use error_handling, only: error_t
use sqrt_inplace_mod, only: sqrt_inplace
implicit none
real :: x
class(error_t), allocatable :: error
! Here we use a labelled block to separate multiple fallible
! procedure calls from the code that handles any errors
fallible: block
write(*,*) 'computing square root...'
x = 20.0
call sqrt_inplace(x, error)
! If an error occurred, go to error handling code
if (allocated(error)) exit fallible
! Success -> write result
write(*,*) ' - sqrt = ', x
write(*,*) 'computing square root...'
x = - 20.0
call sqrt_inplace(x, error)
if (allocated(error)) exit fallible
write(*,*) ' - sqrt = ', x
! Return from subroutine on success, code below is only for
! error handling so no allocated(error) check is needed there.
return
end block fallible
! If we're here then an error has happened!
write(*, '(a,a)') 'Error: ', error%to_chars()For enabling stacktraces from errors, see instructions here.
A fairly recent Fortran and compiler is required to build this library. The following compilers are known to work:
-
gfortran version 9 or later
-
Intel Fortran 2021 or later
The recommended way of getting the source code for this library when using CMake is to add it as a dependency using CMake Package Manager (CPM):
CPMAddPackage("https://github.com/SINTEF/[email protected]")
target_link_libraries(<your target> error-handling)If you don’t want to use CPM you can either use
FetchContent
manually or add this repo as a git submodule to your project. Then in your
CMakeLists.txt add it as a subdirectory and use target_link_libraries to
link against error-handling.
The abstract error_t class is declared in the error_mod module,
but also available as a re-export from the error_handling module for convenience.
The rest of the public API is available from the error_handling
module which also contains documentation for each type and procedure.
After trying out the Quick Start, see the sections below for some more advanced features in this library.
For the developer a stacktrace is an invaluable resource for determining the reason of an error. For users however, the stacktrace is hardly of any use at all. This is why it is important to gracefully unwind the application and provide some information about what caused the error so that users may take action themselves.
The example below shows how the subroutine wrap_error can be used to provide
contextual information in the event of an error.
In fact this information will be very useful for a developer as well since the stacktrace
from a successful invocation of accumulate_and_check looks exactly the same as
the one that fails.
module processing_mod
use error_handling, only: error_t, wrap_error, fail
implicit none
contains
pure subroutine process_array(arr, res, error)
integer, intent(inout) :: arr(:)
integer, intent(out) :: res
class(error_t), allocatable, intent(inout) :: error
integer :: i
character(len=20) :: i_value
! Here we use a labelled block to separate multiple fallible procedure calls
! from the code that handles any errors
res = 0
fallible: block
do i = 1, size(arr)
call check_and_accumulate(arr(i), res, error)
if (allocated(error)) exit fallible
end do
! Return for subroutine on success, code below is only for
! error handling so no allocated(error) check is needed there.
return
end block fallible
! Provide some context with error
write(i_value, *) i
call wrap_error(error, 'Processing of array failed at element ' &
// trim(adjustl(i_value)))
end subroutine
pure subroutine check_and_accumulate(i, res, error)
integer, intent(in) :: i
integer, intent(inout) :: res
class(error_t), allocatable, intent(inout) :: error
if (res > 50) then
error = fail('Magic limit reached')
return
end if
res = res + i
end subroutine
end module
program basic_example
use error_handling, only: error_t, wrap_error
use processing_mod, only: process_array
implicit none
integer :: res
integer, allocatable :: arr(:)
class(error_t), allocatable :: error
arr = [1, 2, 3, 5, 8, 12, 11, 20, 5, 2, 4, 6]
call process_array(arr, res, error)
if (allocated(error)) then
call wrap_error(error, 'Example failed (but that was the intent...)')
write(*,'(a,a)') 'Error: ', error%to_chars()
else
write(*,*) 'Got back: ', res
end if
end programThis will produce an error message that is quite readable even for those not familiar with the source code:
Error: Example failed (but that was the intent...)
Caused by:
- Processing of array failed at element 9
- Magic limit reachedPure and elemental subroutines can have multiple arguments with intent(inout)
or intent(out).
This makes it possible to modify one or more arguments and have an additional
error_t argument for communicating if any error has ocurred.
Pure and elemental functions on the other hand are only allowed to modify their
return value which means that one cannot add an error_t argument with
intent(inout) to indicate failures.
One way of dealing with this is to return a type which can either hold the result
ing data or an error_t, for example:
type :: result_int_t
integer, allocatable :: value
type(error_t), allocatable :: error
end type|
Warning
|
Technically, this type can also hold a value AND an error. The programmer must make sure that this does not happen. |
This idea is very similar to the
Result
enum in the Rust programming language.
Since Fortran neither have generics
nor any support for sum data types
(enums) this is quite a bit more cumbersome to set up in Fortran.
The module error_handling_experimental_result
provide such result types for some primitive data types. Example:
use iso_fortran_env, only: dp => real64
use error_handling_experimental_result, only: result_real_dp_rank1_t
use error_handling, only: fail
! (...)
type(result_real_dp_rank1_t) pure function func(x) result(y)
real(dp), intent(in) :: x
if (x >= 0) then
y = x * [1.0, 2.0, 3.0]
else
y = fail('x must be positive')
end if
end functionTo use the function:
type(result_real_dp_rank1_t) :: y
y = func(-12.0_dp)
if (y%is_error()) then
! Handle error here
else
! y%value is safe to use here
end if|
Warning
|
This is currently an experimental feature. Expect breaking changes in the future. |
In some situations it might be desirable to detect and handle specific error conditions, for example in order to continue execution. If you’re developing a library for others to use it is good practice to do so as you don’t know how users may wish to use your library.
In these situations, make your own type(s) that extend error_t. Checking for
this specific error can the be done using a select type statement:
class(error_t), allocatable :: error
! (...)
select type (error)
type is (my_error_t)
! Add code here to gracefully handle an error of type my_error_t
end selectNote that due to limitations in the Fortran standard
(see #242)
you should still have subroutines take a class(error_t) argument and not
a type(my_error_t) argument.
If you use a type(my_error_t) and any caller just want to pass errors
back up the call stack then they need to add much boilerplate code to convert the
type(my_error_t) variable into a class(error_t).
Instead, use an argument class(error_t) and clearly state the possible error types
that might be returned in the documentation.
It is also worth noting that any custom error handler (e.g. for stacktrace generation)
will not be attached to the custom error type.
This will first happen when the error is stored in the general error report type by
either the fail function or the wrap_error subroutine.
For a complete example, see custom-error-type.f90.
The design of this library is heavily inspired by error handling mechanisms in the Rust programming language and specifically the Rust library eyre. Rust don’t use exceptions like many other popular programming languages. Interestingly this means that error handling in Fortran - one of the oldest programming languages still actively used - share certain patterns with one of the more "modern" programming languages around.
The vast majority of all source code includes error scenarios of some sorts. Fundamentally, a good method for handling errors in Fortran should satisfy the following requirements:
-
Usable both in pure and impure subroutines and functions.
-
Low overhead, especially for successful calls.
-
Errors should be difficult to overlook. It should be obvious for the developer that they need to check if something went wrong.
-
It should be possible to provide accurate information about what failed and when it occurred.
-
Some errors might need to be recoverable, i.e. the caller of a procedure should be able to programmatically detect and act if a certain error occurred.
There are many ways of designing a error handling system for Fortran. This library satisfies the above requirements and should be reasonably easy to use. Some design decisions in might however not be obvious at first glance, but are done so for good reasons:
- Why is a second library required for stacktrace generation?
-
The stacktrace generation code requires some additional dependencies, namely a C++ compiler, some Win32 API calls on Windows and libbfd on Linux. For complex project this might not be a big deal, but smaller projects it could be advantageous to have a simple pure Fortran library instead. Also, the error context generation using
wrap_erroris very useful by itself, even without code to generate a stacktrace along with it.