pic_error Module

Unified error handling with stack traces for PIC. Use error_t as an intent(out) or intent(inout) argument to propagate errors with context through call chains.

Basic usage: type(error_t) :: err call err%set(ERROR_IO, “failed to open file”) if (err%has_error()) call err%fatal() ! Or using operator: if (.haserror. err) call err%fatal()

Error wrapping (Rust-style “caused by”, outermost first): call low_level_routine(err) if (err%has_error()) then call err%wrap(ERROR_PARSE, “failed to parse input”) return end if Error codes Stack trace configuration


Uses

  • module~~pic_error~~UsesGraph module~pic_error pic_error module~pic_global_definitions pic_global_definitions module~pic_error->module~pic_global_definitions module~pic_types pic_types module~pic_error->module~pic_types module~pic_global_definitions->module~pic_types iso_c_binding iso_c_binding module~pic_types->iso_c_binding iso_fortran_env iso_fortran_env module~pic_types->iso_fortran_env

Variables

Type Visibility Attributes Name Initial
integer(kind=default_int), public, parameter :: ERROR_ALLOC = 5
integer(kind=default_int), public, parameter :: ERROR_GENERIC = 1
integer(kind=default_int), public, parameter :: ERROR_IO = 2
integer(kind=default_int), public, parameter :: ERROR_PARSE = 3
integer(kind=default_int), public, parameter :: ERROR_VALIDATION = 4
integer(kind=default_int), public, parameter :: SUCCESS = 0
integer(kind=default_int), private, parameter :: MAX_CAUSE_DEPTH = 8
integer(kind=default_int), private, parameter :: MAX_CAUSE_MSG_LEN = 256

Unified error type with stack trace support
integer(kind=default_int), private, parameter :: MAX_LOCATION_LEN = 128

Cause chain configuration
integer(kind=default_int), private, parameter :: MAX_STACK_DEPTH = 20

Interfaces

public interface operator(.haserror.)

Operator for checking error state: if (.haserror. err) then

  • private pure function error_has_error(self) result(has_err)

    Check if an error is set

    Arguments

    Type IntentOptional Attributes Name
    class(error_t), intent(in) :: self

    Return Value logical


Derived Types

type, public ::  error_t

Components

Type Visibility Attributes Name Initial
character(len=MAX_LOCATION_LEN), public :: call_stack(MAX_STACK_DEPTH)

Call locations

Read more…
integer(kind=default_int), public :: cause_codes(MAX_CAUSE_DEPTH)

Error codes of wrapped causes
integer(kind=default_int), public :: cause_depth = 0

Number of wrapped causes
character(len=MAX_CAUSE_MSG_LEN), public :: cause_messages(MAX_CAUSE_DEPTH)

Messages of wrapped causes
integer(kind=default_int), public :: code = SUCCESS

Error code (0 = no error)
character(len=:), public, allocatable :: message

Error message

Read more…
integer(kind=default_int), public :: stack_depth = 0

Current stack depth

Type-Bound Procedures

procedure, public :: add_context => error_add_context
procedure, public :: clear => error_clear
procedure, public :: fatal => error_fatal
procedure, public :: get_code => error_get_code
procedure, public :: get_full_trace => error_get_full_trace
procedure, public :: get_message => error_get_message
procedure, public :: has_error => error_has_error
procedure, public :: is => error_is
procedure, public :: print_trace => error_print_trace
procedure, public :: set => error_set
procedure, public :: wrap => error_wrap

Functions

public pure function code_to_string(code) result(name)

Map an error code to a human-readable name

Read more…

Arguments

Type IntentOptional Attributes Name
integer(kind=default_int), intent(in) :: code

Return Value character(len=:), allocatable

private pure function error_get_code(self) result(code)

Get the error code

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self

Return Value integer(kind=default_int)

private function error_get_full_trace(self) result(trace)

Get complete error message with cause chain and stack trace Returns a dynamically-sized multi-line string

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self

Return Value character(len=:), allocatable

private pure function error_get_message(self) result(message)

Get the error message (without stack trace)

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self

Return Value character(len=:), allocatable

private pure function error_has_error(self) result(has_err)

Check if an error is set

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self

Return Value logical

private pure function error_is(self, code) result(matches)

Check if the error matches a specific error code

Read more…

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self
integer(kind=default_int), intent(in) :: code

Return Value logical


Subroutines

private pure subroutine error_add_context(self, location)

Add a call location to the stack trace Typically called when propagating errors upward

Read more…

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(inout) :: self
character(len=*), intent(in) :: location

private pure subroutine error_clear(self)

Clear the error state, stack trace, and cause chain

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(inout) :: self

private subroutine error_fatal(self, unit)

Print the error trace and stop the program Use for unrecoverable errors

Read more…

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self
integer(kind=default_int), intent(in), optional :: unit

private subroutine error_print_trace(self, unit)

Print error with cause chain and stack trace to specified unit If unit not specified, prints to stdout

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(in) :: self
integer(kind=default_int), intent(in), optional :: unit

private pure subroutine error_set(self, code, message)

Set an error with code and message Resets the stack trace and cause chain

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(inout) :: self
integer(kind=default_int), intent(in) :: code
character(len=*), intent(in) :: message

private pure subroutine error_wrap(self, code, message)

Wrap the current error with a higher-level context Pushes the current error into the cause chain and sets a new top-level code and message (Rust-style “caused by”)

Read more…

Arguments

Type IntentOptional Attributes Name
class(error_t), intent(inout) :: self
integer(kind=default_int), intent(in) :: code
character(len=*), intent(in) :: message