error_raise Subroutine

public pure subroutine error_raise(err, code, message)

Set an optional error argument, if the caller supplied one.

This exists for the very common propagation pattern in PIC’s pure numerical code, which declares type(error_t), intent(inout), optional :: err and would otherwise need an explicit if (present(err)) guard at every single failure site:

pure subroutine sort_something(a, err) type(error_t), intent(inout), optional :: err if (size(a) < 0) then call error_raise(err, ERROR_BOUNDS, “negative extent”) return end if

IMPORTANT LIMITATION - the error can be silently dropped. When err is absent this routine does nothing at all: it cannot print, and it cannot error stop either, because a pure procedure may only error stop with a constant message and PIC will not abort a library call on the caller’s behalf. A caller that does not pass err therefore receives NO indication that anything went wrong, and must be able to tolerate that. If you need to be told about failures, pass err and check it.

Like set, this resets any existing stack trace and cause chain on err; it does not wrap what was already there.

Arguments

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

Calls

proc~~error_raise~~CallsGraph proc~error_raise error_raise proc~error_set error_t%error_set proc~error_raise->proc~error_set

Called by

proc~~error_raise~~CalledByGraph proc~error_raise error_raise none~merge_sort merge_sort none~merge_sort->proc~error_raise none~merge_sort~10 merge_sort none~merge_sort~10->proc~error_raise none~merge_sort~11 merge_sort none~merge_sort~11->proc~error_raise none~merge_sort~12 merge_sort none~merge_sort~12->proc~error_raise none~merge_sort~13 merge_sort none~merge_sort~13->proc~error_raise none~merge_sort~14 merge_sort none~merge_sort~14->proc~error_raise none~merge_sort~15 merge_sort none~merge_sort~15->proc~error_raise none~merge_sort~16 merge_sort none~merge_sort~16->proc~error_raise none~merge_sort~17 merge_sort none~merge_sort~17->proc~error_raise none~merge_sort~18 merge_sort none~merge_sort~18->proc~error_raise none~merge_sort~19 merge_sort none~merge_sort~19->proc~error_raise none~merge_sort~2 merge_sort none~merge_sort~2->proc~error_raise none~merge_sort~20 merge_sort none~merge_sort~20->proc~error_raise none~merge_sort~3 merge_sort none~merge_sort~3->proc~error_raise none~merge_sort~4 merge_sort none~merge_sort~4->proc~error_raise none~merge_sort~5 merge_sort none~merge_sort~5->proc~error_raise none~merge_sort~6 merge_sort none~merge_sort~6->proc~error_raise none~merge_sort~7 merge_sort none~merge_sort~7->proc~error_raise none~merge_sort~8 merge_sort none~merge_sort~8->proc~error_raise none~merge_sort~9 merge_sort none~merge_sort~9->proc~error_raise proc~char_decrease_ord_sort char_decrease_ord_sort proc~char_decrease_ord_sort->proc~error_raise proc~char_decrease_ord_sort->none~merge_sort~20 proc~char_increase_ord_sort char_increase_ord_sort proc~char_increase_ord_sort->proc~error_raise proc~char_increase_ord_sort->none~merge_sort~15 proc~char_sort_index_default char_sort_index_default proc~char_sort_index_default->proc~error_raise proc~char_sort_index_default->none~merge_sort~5 proc~char_sort_index_low char_sort_index_low proc~char_sort_index_low->proc~error_raise proc~char_sort_index_low->none~merge_sort~10 proc~copy_3d_tensor_dp copy_3d_tensor_dp proc~copy_3d_tensor_dp->proc~error_raise proc~copy_3d_tensor_int32 copy_3d_tensor_int32 proc~copy_3d_tensor_int32->proc~error_raise proc~copy_3d_tensor_int64 copy_3d_tensor_int64 proc~copy_3d_tensor_int64->proc~error_raise proc~copy_3d_tensor_sp copy_3d_tensor_sp proc~copy_3d_tensor_sp->proc~error_raise proc~copy_matrix_dp copy_matrix_dp proc~copy_matrix_dp->proc~error_raise proc~copy_matrix_int32 copy_matrix_int32 proc~copy_matrix_int32->proc~error_raise proc~copy_matrix_int64 copy_matrix_int64 proc~copy_matrix_int64->proc~error_raise proc~copy_matrix_sp copy_matrix_sp proc~copy_matrix_sp->proc~error_raise proc~copy_vector_dp copy_vector_dp proc~copy_vector_dp->proc~error_raise proc~copy_vector_int32 copy_vector_int32 proc~copy_vector_int32->proc~error_raise proc~copy_vector_int64 copy_vector_int64 proc~copy_vector_int64->proc~error_raise proc~copy_vector_sp copy_vector_sp proc~copy_vector_sp->proc~error_raise proc~dp_decrease_ord_sort dp_decrease_ord_sort proc~dp_decrease_ord_sort->proc~error_raise proc~dp_decrease_ord_sort->none~merge_sort~19 proc~dp_increase_ord_sort dp_increase_ord_sort proc~dp_increase_ord_sort->proc~error_raise proc~dp_increase_ord_sort->none~merge_sort~14 proc~dp_radix_sort dp_radix_sort proc~dp_radix_sort->proc~error_raise proc~dp_sort_index_default dp_sort_index_default proc~dp_sort_index_default->proc~error_raise proc~dp_sort_index_default->none~merge_sort~4 proc~dp_sort_index_low dp_sort_index_low proc~dp_sort_index_low->proc~error_raise proc~dp_sort_index_low->none~merge_sort~9 proc~int32_decrease_ord_sort int32_decrease_ord_sort proc~int32_decrease_ord_sort->proc~error_raise proc~int32_decrease_ord_sort->none~merge_sort~16 proc~int32_increase_ord_sort int32_increase_ord_sort proc~int32_increase_ord_sort->proc~error_raise proc~int32_increase_ord_sort->none~merge_sort~11 proc~int32_radix_sort int32_radix_sort proc~int32_radix_sort->proc~error_raise proc~int32_sort_index_default int32_sort_index_default proc~int32_sort_index_default->proc~error_raise proc~int32_sort_index_default->none~merge_sort proc~int32_sort_index_low int32_sort_index_low proc~int32_sort_index_low->proc~error_raise proc~int32_sort_index_low->none~merge_sort~6 proc~int64_decrease_ord_sort int64_decrease_ord_sort proc~int64_decrease_ord_sort->proc~error_raise proc~int64_decrease_ord_sort->none~merge_sort~17 proc~int64_increase_ord_sort int64_increase_ord_sort proc~int64_increase_ord_sort->proc~error_raise proc~int64_increase_ord_sort->none~merge_sort~12 proc~int64_radix_sort int64_radix_sort proc~int64_radix_sort->proc~error_raise proc~int64_sort_index_default int64_sort_index_default proc~int64_sort_index_default->proc~error_raise proc~int64_sort_index_default->none~merge_sort~2 proc~int64_sort_index_low int64_sort_index_low proc~int64_sort_index_low->proc~error_raise proc~int64_sort_index_low->none~merge_sort~7 proc~now_local now_local proc~now_local->proc~error_raise proc~now_utc now_utc proc~now_utc->proc~error_raise proc~now_utc->proc~now_local proc~print_packed_matrix_dp print_packed_matrix_dp proc~print_packed_matrix_dp->proc~error_raise proc~set_brackets set_brackets proc~print_packed_matrix_dp->proc~set_brackets proc~print_packed_matrix_int32 print_packed_matrix_int32 proc~print_packed_matrix_int32->proc~error_raise proc~print_packed_matrix_int32->proc~set_brackets proc~print_packed_matrix_int64 print_packed_matrix_int64 proc~print_packed_matrix_int64->proc~error_raise proc~print_packed_matrix_int64->proc~set_brackets proc~print_packed_matrix_sp print_packed_matrix_sp proc~print_packed_matrix_sp->proc~error_raise proc~print_packed_matrix_sp->proc~set_brackets proc~set_brackets->proc~error_raise proc~sp_decrease_ord_sort sp_decrease_ord_sort proc~sp_decrease_ord_sort->proc~error_raise proc~sp_decrease_ord_sort->none~merge_sort~18 proc~sp_increase_ord_sort sp_increase_ord_sort proc~sp_increase_ord_sort->proc~error_raise proc~sp_increase_ord_sort->none~merge_sort~13 proc~sp_radix_sort sp_radix_sort proc~sp_radix_sort->proc~error_raise proc~sp_sort_index_default sp_sort_index_default proc~sp_sort_index_default->proc~error_raise proc~sp_sort_index_default->none~merge_sort~3 proc~sp_sort_index_low sp_sort_index_low proc~sp_sort_index_low->proc~error_raise proc~sp_sort_index_low->none~merge_sort~8 proc~transpose_matrix_dp transpose_matrix_dp proc~transpose_matrix_dp->proc~error_raise proc~transpose_matrix_int32 transpose_matrix_int32 proc~transpose_matrix_int32->proc~error_raise proc~transpose_matrix_int64 transpose_matrix_int64 proc~transpose_matrix_int64->proc~error_raise proc~transpose_matrix_sp transpose_matrix_sp proc~transpose_matrix_sp->proc~error_raise proc~vec_dp_append vector_dp_t%vec_dp_append proc~vec_dp_append->proc~error_raise proc~vec_dp_grow vec_dp_grow proc~vec_dp_append->proc~vec_dp_grow proc~vec_dp_at vector_dp_t%vec_dp_at proc~vec_dp_at->proc~error_raise proc~vec_dp_grow->proc~error_raise proc~vec_dp_pop_back vector_dp_t%vec_dp_pop_back proc~vec_dp_pop_back->proc~error_raise proc~vec_dp_push_back vector_dp_t%vec_dp_push_back proc~vec_dp_push_back->proc~error_raise proc~vec_dp_push_back->proc~vec_dp_grow proc~vec_dp_resize vector_dp_t%vec_dp_resize proc~vec_dp_resize->proc~error_raise proc~vec_dp_resize->proc~vec_dp_grow proc~vec_dp_set vector_dp_t%vec_dp_set proc~vec_dp_set->proc~error_raise proc~vec_dp_shrink_to_fit vector_dp_t%vec_dp_shrink_to_fit proc~vec_dp_shrink_to_fit->proc~error_raise proc~vec_int32_append vector_int32_t%vec_int32_append proc~vec_int32_append->proc~error_raise proc~vec_int32_grow vec_int32_grow proc~vec_int32_append->proc~vec_int32_grow proc~vec_int32_at vector_int32_t%vec_int32_at proc~vec_int32_at->proc~error_raise proc~vec_int32_grow->proc~error_raise proc~vec_int32_pop_back vector_int32_t%vec_int32_pop_back proc~vec_int32_pop_back->proc~error_raise proc~vec_int32_push_back vector_int32_t%vec_int32_push_back proc~vec_int32_push_back->proc~error_raise proc~vec_int32_push_back->proc~vec_int32_grow proc~vec_int32_resize vector_int32_t%vec_int32_resize proc~vec_int32_resize->proc~error_raise proc~vec_int32_resize->proc~vec_int32_grow proc~vec_int32_set vector_int32_t%vec_int32_set proc~vec_int32_set->proc~error_raise proc~vec_int32_shrink_to_fit vector_int32_t%vec_int32_shrink_to_fit proc~vec_int32_shrink_to_fit->proc~error_raise proc~vec_int64_append vector_int64_t%vec_int64_append proc~vec_int64_append->proc~error_raise proc~vec_int64_grow vec_int64_grow proc~vec_int64_append->proc~vec_int64_grow proc~vec_int64_at vector_int64_t%vec_int64_at proc~vec_int64_at->proc~error_raise proc~vec_int64_grow->proc~error_raise proc~vec_int64_pop_back vector_int64_t%vec_int64_pop_back proc~vec_int64_pop_back->proc~error_raise proc~vec_int64_push_back vector_int64_t%vec_int64_push_back proc~vec_int64_push_back->proc~error_raise proc~vec_int64_push_back->proc~vec_int64_grow proc~vec_int64_resize vector_int64_t%vec_int64_resize proc~vec_int64_resize->proc~error_raise proc~vec_int64_resize->proc~vec_int64_grow proc~vec_int64_set vector_int64_t%vec_int64_set proc~vec_int64_set->proc~error_raise proc~vec_int64_shrink_to_fit vector_int64_t%vec_int64_shrink_to_fit proc~vec_int64_shrink_to_fit->proc~error_raise proc~vec_string_append vector_string_t%vec_string_append proc~vec_string_append->proc~error_raise proc~vec_string_grow vec_string_grow proc~vec_string_append->proc~vec_string_grow proc~vec_string_at vector_string_t%vec_string_at proc~vec_string_at->proc~error_raise proc~vec_string_grow->proc~error_raise proc~vec_string_pop_back vector_string_t%vec_string_pop_back proc~vec_string_pop_back->proc~error_raise proc~vec_string_push_back vector_string_t%vec_string_push_back proc~vec_string_push_back->proc~error_raise proc~vec_string_push_back->proc~vec_string_grow proc~vec_string_resize vector_string_t%vec_string_resize proc~vec_string_resize->proc~error_raise proc~vec_string_resize->proc~vec_string_grow proc~vec_string_set vector_string_t%vec_string_set proc~vec_string_set->proc~error_raise proc~vec_string_shrink_to_fit vector_string_t%vec_string_shrink_to_fit proc~vec_string_shrink_to_fit->proc~error_raise interface~pic_copy pic_copy interface~pic_copy->proc~copy_3d_tensor_dp interface~pic_copy->proc~copy_3d_tensor_int32 interface~pic_copy->proc~copy_3d_tensor_int64 interface~pic_copy->proc~copy_3d_tensor_sp interface~pic_copy->proc~copy_matrix_dp interface~pic_copy->proc~copy_matrix_int32 interface~pic_copy->proc~copy_matrix_int64 interface~pic_copy->proc~copy_matrix_sp interface~pic_copy->proc~copy_vector_dp interface~pic_copy->proc~copy_vector_int32 interface~pic_copy->proc~copy_vector_int64 interface~pic_copy->proc~copy_vector_sp interface~pic_print_array pic_print_array interface~pic_print_array->proc~print_packed_matrix_dp interface~pic_print_array->proc~print_packed_matrix_int32 interface~pic_print_array->proc~print_packed_matrix_int64 interface~pic_print_array->proc~print_packed_matrix_sp proc~print_3d_tensor_dp print_3d_tensor_dp interface~pic_print_array->proc~print_3d_tensor_dp proc~print_3d_tensor_int32 print_3d_tensor_int32 interface~pic_print_array->proc~print_3d_tensor_int32 proc~print_3d_tensor_int64 print_3d_tensor_int64 interface~pic_print_array->proc~print_3d_tensor_int64 proc~print_3d_tensor_sp print_3d_tensor_sp interface~pic_print_array->proc~print_3d_tensor_sp proc~print_matrix_dp print_matrix_dp interface~pic_print_array->proc~print_matrix_dp proc~print_matrix_int32 print_matrix_int32 interface~pic_print_array->proc~print_matrix_int32 proc~print_matrix_int64 print_matrix_int64 interface~pic_print_array->proc~print_matrix_int64 proc~print_matrix_sp print_matrix_sp interface~pic_print_array->proc~print_matrix_sp proc~print_vector_dp print_vector_dp interface~pic_print_array->proc~print_vector_dp proc~print_vector_int32 print_vector_int32 interface~pic_print_array->proc~print_vector_int32 proc~print_vector_int64 print_vector_int64 interface~pic_print_array->proc~print_vector_int64 proc~print_vector_sp print_vector_sp interface~pic_print_array->proc~print_vector_sp interface~pic_transpose pic_transpose interface~pic_transpose->proc~transpose_matrix_dp interface~pic_transpose->proc~transpose_matrix_int32 interface~pic_transpose->proc~transpose_matrix_int64 interface~pic_transpose->proc~transpose_matrix_sp proc~char_ord_sort char_ord_sort proc~char_ord_sort->proc~char_decrease_ord_sort proc~char_ord_sort->proc~char_increase_ord_sort proc~dp_ord_sort dp_ord_sort proc~dp_ord_sort->proc~dp_decrease_ord_sort proc~dp_ord_sort->proc~dp_increase_ord_sort proc~int32_ord_sort int32_ord_sort proc~int32_ord_sort->proc~int32_decrease_ord_sort proc~int32_ord_sort->proc~int32_increase_ord_sort proc~int64_ord_sort int64_ord_sort proc~int64_ord_sort->proc~int64_decrease_ord_sort proc~int64_ord_sort->proc~int64_increase_ord_sort proc~print_3d_tensor_dp->proc~set_brackets proc~print_3d_tensor_dp->interface~pic_print_array proc~print_3d_tensor_int32->proc~set_brackets proc~print_3d_tensor_int32->interface~pic_print_array proc~print_3d_tensor_int64->proc~set_brackets proc~print_3d_tensor_int64->interface~pic_print_array proc~print_3d_tensor_sp->proc~set_brackets proc~print_3d_tensor_sp->interface~pic_print_array proc~print_matrix_dp->proc~set_brackets proc~print_matrix_int32->proc~set_brackets proc~print_matrix_int64->proc~set_brackets proc~print_matrix_sp->proc~set_brackets proc~print_vector_dp->proc~set_brackets proc~print_vector_int32->proc~set_brackets proc~print_vector_int64->proc~set_brackets proc~print_vector_sp->proc~set_brackets proc~sp_ord_sort sp_ord_sort proc~sp_ord_sort->proc~sp_decrease_ord_sort proc~sp_ord_sort->proc~sp_increase_ord_sort proc~vec_dp_reserve vector_dp_t%vec_dp_reserve proc~vec_dp_reserve->proc~vec_dp_grow proc~vec_dp_take vector_dp_t%vec_dp_take proc~vec_dp_take->proc~vec_dp_shrink_to_fit proc~vec_int32_reserve vector_int32_t%vec_int32_reserve proc~vec_int32_reserve->proc~vec_int32_grow proc~vec_int32_take vector_int32_t%vec_int32_take proc~vec_int32_take->proc~vec_int32_shrink_to_fit proc~vec_int64_reserve vector_int64_t%vec_int64_reserve proc~vec_int64_reserve->proc~vec_int64_grow proc~vec_int64_take vector_int64_t%vec_int64_take proc~vec_int64_take->proc~vec_int64_shrink_to_fit proc~vec_string_reserve vector_string_t%vec_string_reserve proc~vec_string_reserve->proc~vec_string_grow proc~vec_string_take vector_string_t%vec_string_take proc~vec_string_take->proc~vec_string_shrink_to_fit

Source Code

   pure subroutine error_raise(err, code, message)
      !! Set an optional error argument, if the caller supplied one.
      !!
      !! This exists for the very common propagation pattern in PIC's `pure`
      !! numerical code, which declares `type(error_t), intent(inout),
      !! optional :: err` and would otherwise need an explicit
      !! `if (present(err))` guard at every single failure site:
      !!
      !!   pure subroutine sort_something(a, err)
      !!      type(error_t), intent(inout), optional :: err
      !!      if (size(a) < 0) then
      !!         call error_raise(err, ERROR_BOUNDS, "negative extent")
      !!         return
      !!      end if
      !!
      !! IMPORTANT LIMITATION - the error can be silently dropped. When `err`
      !! is absent this routine does nothing at all: it cannot print, and it
      !! cannot `error stop` either, because a `pure` procedure may only
      !! `error stop` with a constant message and PIC will not abort a
      !! library call on the caller's behalf. A caller that does not pass
      !! `err` therefore receives NO indication that anything went wrong, and
      !! must be able to tolerate that. If you need to be told about
      !! failures, pass `err` and check it.
      !!
      !! Like `set`, this resets any existing stack trace and cause chain on
      !! `err`; it does not wrap what was already there.
      type(error_t), intent(inout), optional :: err
      integer(default_int), intent(in) :: code
      character(len=*), intent(in) :: message

      if (present(err)) call err%set(code, message)
   end subroutine error_raise