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.
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; nonedraw_checks: The input's problems, above the treereset_layout: Load the layout the program set; the file may have gone sincecode_name: The name of a status code, for a messagedraw_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_popupwithout 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
statand 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:
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.
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 failedlist = 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
enddoproblemsgives one line per failed check (packkeeps 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_runrefuses a run while there are problems: the Run button is greyed out, and its tooltip says why.
The solver's exit codes
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 wordsThe 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
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, andig_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_iconreturnsFIG_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.