Skip to content

16. Robustness ​

A tool is trusted when it says what went wrong. This chapter goes through the studio's failures: an input it cannot read, an input that reads but makes no sense, a solver that does not converge, a file of the user's that is gone. Each gets a message in words, at the place the user looks, and a Messages panel keeps them all.

docs/examples/src/tut16_robust.F90, run as tut16_robust --examples /tmp/figure-studio --case /tmp/figure-studio/plate

The whole program: tut16_robust.F90.

What this chapter adds to chapter 15's program, tut15_task.F90:

  • problems: What is wrong with an input, one line each; none
  • draw_checks: The input's problems, above the tree
  • reset_layout: Load the layout the program set; the file may have gone since
  • code_name: The name of a status code, for a message
  • draw_messages: Every notification of this session, newest first
  • changed: draw_input, draw_menus, draw_panels, draw_run, follow_run, write_examples

stat or stop ​

Every FIGURE procedure that can fail takes an optional stat (Error handling). Without it, a failure prints FIGURE error: <message> and stops the program; with it, the program gets the status and figure_last_error() the message. Which to use depends on what failed:

  • A mistake in the program (an unknown colormap name written in the source, arrays of different sizes, an ig_end_popup without its begin): stopping is right. It shows at the first run, with a message that names it.
  • Something of the user's or of the system's (a file gone or unreadable, a program that cannot be started, a display without window icons, a folder that cannot be written): it happens to a correct program, so the program passes stat and tells the user.

The studio passes stat since chapter 8 where the second kind can happen: set_icon, the process's start, the browser's answer, the task's result; and now the layout files:

fortran
call app%load_layout(DEFAULT_LAYOUT, stat=stat)   ! a file of the user's: it can be gone or broken
if (stat /= FIG_OK) call app%notify(code_name(stat)//': '//figure_last_error(), kind='error')

figure_last_error() gives the message of the last failure: read it right after the call. The status code tells the kind: FIG_ERR_STATE (not now), FIG_ERR_ARGUMENT (not this), FIG_ERR_FAILED (the system said no), FIG_ERR_EXCEPTION (Status codes). The layout saved at the first frame passes stat too: in a folder that cannot be written, Reset layout stays greyed out.

Messages of the run time ​

A namelist that does not read is reported by Fortran itself: read(u, nml=heat, iostat=ios, iomsg=msg) gives the status and the run time's own message, which names the problem (Cannot match namelist object name omgea). Chapter 10 already shows it in a warning and keeps the open case; the case with the typo is among the examples.

Checking the input ​

An input can read and still make no sense: a body outside the plate, every side insulated (the temperature is then not determined), an over-relaxation factor of 2. The solver would run, and fail or loop; the studio checks first.

fortran
what(1) = 'the grid needs at least 3 x 3 nodes'
bad(1) = c%nx < 3_int32 .or. c%ny < 3_int32
what(2) = 'the plate needs a positive size'
bad(2) = c%lx <= 0.0_real64 .or. c%ly <= 0.0_real64
what(3) = 'the body reaches the plate''s edge'
bad(3) = c%body_x - c%body_r <= 0.0_real64 .or. c%body_x + c%body_r >= c%lx .or. &
         c%body_y - c%body_r <= 0.0_real64 .or. c%body_y + c%body_r >= c%ly
what(4) = 'every side insulated: the temperature is not determined'
bad(4) = all(c%bc_kind == 'insulated')
what(5) = 'omega must be in (0, 2): over-relaxation diverges at 2'
bad(5) = c%omega <= 0.0_real64 .or. c%omega >= 2.0_real64
what(6) = 'the tolerance must be positive'
bad(6) = c%tolerance <= 0.0_real64
what(7) = 'at least one iteration'
bad(7) = c%max_iter < 1_int32
list = pack(what, bad)                            ! the messages of the checks that failed
fortran
list = problems(inp)
if (size(list) == 0) return
call app%palette_color('error', red)              ! the palette's: right in a light palette and in a dark one
do k = 1_int32, size(list, kind=int32)
   call ig_text_colored('[!!] '//trim(list(k)), red) ! a mark with the colour: never colour alone
enddo
  • problems gives one line per failed check (pack keeps the messages whose check failed); an empty list means the input can run.
  • The Input panel shows them above the tree, each marked [!!] in the palette's error colour: app%palette_color('error', rgba) gives the role's colour in the palette in effect, right in a light palette and in a dark one (Palette roles). The mark carries the meaning without the colour.
  • can_run refuses a run while there are problems: the Run button is greyed out, and its tooltip says why.

The solver's exit codes ​

fortran
select case (solver%exit_code())                ! the solver's own codes (tut12_heat.F90)
case (1_int32)
   run_status = 'the solver cannot read heat.inp: see the log'
case (2_int32)
   write(run_status, '(A,I0,A)') 'not converged in ', inp%max_iter, ' iterations: raise max_iter or omega'
case default
   write(run_status, '(A,I0,A)') 'the solver failed, exit code ', solver%exit_code(), ': see the log'
endselect
call app%notify(trim(run_status), kind='error', seconds=8.0_real64) ! the notification has its own mark
run_status = '[!!] '//trim(run_status)          ! the status bar's: a mark with the words

The solver ends with a code of its own: 0 converged, 1 the input cannot be read, 2 not converged (it stops with stop 2, quiet=.true.: the code, without a message or a backtrace). The studio turns each into a sentence that says what to do next, in an error notification and, with a [!!] mark, in the status bar.

A history of the messages ​

fortran
call app%notifications(list, kinds, shown)        ! the last 100, oldest first
if (size(list) == 0) call ig_text_disabled('No message yet.')
do k = size(list, kind=int32), 1_int32, -1_int32
   select case (kinds(k))
   case ('error')
      call app%palette_color('error', rgba)
      call ig_text_colored('[!!] '//trim(list(k)), rgba)
   case ('warning')
      call app%palette_color('warning', rgba)
      call ig_text_colored('(!)  '//trim(list(k)), rgba)
   case ('success')
      call app%palette_color('success', rgba)
      call ig_text_colored('[ok] '//trim(list(k)), rgba)
   case default
      call ig_text('     '//trim(list(k)))
   endselect
enddo
  • A notification fades after a few seconds; the user may have looked elsewhere. app%notifications(list, kinds, shown) gives the last 100, oldest first, with their kinds, and the Messages panel lists them newest first, each with its mark and its role's colour (Notifications).
  • The panel opens from Help > Messages, as a tab beside Run the first time: ig_window_dock(id, docked), called in the Run panel, gives Run's dock node, and ig_set_next_window_dock(id) puts the Messages panel there when it first appears (A window that appears later). Afterwards the user moves it where they like.

The limits the studio lives with ​

Some failures are not the program's to fix, and FIGURE lists them in its known issues. Those the studio meets:

  • No window icon on Wayland compositors without the icon protocol and on SDL's offscreen driver: set_icon returns FIG_ERR_FAILED, the bar keeps its icon (The window's frame).
  • gfortran 16 gives a wrong section of a deferred-length character array to a procedure, and builds an array constructor of deferred-length strings too small (chapter 12): copy into fixed-length arrays first (gfortran).
  • Tasks and nvfortran: formatted I/O on a worker needs -mp (Tasks).
  • The 3-D view has one light, lines one pixel wide, and no axes (3-D views).
  • Remote mode has no system dialogs and no drops (chapter 18).

What you learned

When to pass stat and when to let a failure stop the program; figure_last_error() and the status codes; the run time's iomsg; checks of the input before a run, marked in the palette's error colour; exit codes turned into sentences; a history of the notifications, docked where the program chooses the first time. Reference: Error handling, Notifications, Palette roles, Docking, Known issues.

Run it: build it as chapter 7 shows (with tut12_heat beside it), then ./tut16_robust --examples /tmp/studio --case /tmp/studio/plate.

Next: 17. The studio tested: the studio driven headless by its users' gestures.

Released under the MIT licence.