Skip to content

6. Running work ​

Chapter 4 advanced a computation a little in every frame. Work that cannot be cut into such slices, or that is another program altogether, runs beside the frame loop: the window keeps answering while it runs. This chapter starts a tool from a button and shows what it prints, then runs a computation of the program as a task.

fortran
!< tut06_work_task, tutorial chapter 6: the work run as a task (a module procedure: it runs on a worker thread).
module tut06_work_task
!< tut06_work_task, tutorial chapter 6: the work run as a task (a module procedure: it runs on a worker thread).
use, intrinsic :: iso_fortran_env, only : real64
use figure, only : task_handle_object

implicit none
private
public :: field_t, smooth_field

type :: field_t
   !< A field of values, given to the task and given back smoothed.
   real(real64), allocatable :: v(:) !< Values.
endtype field_t

contains
   recursive subroutine smooth_field(h, data)
   !< Smooth the field 200 times, reporting each pass.
   type(task_handle_object), intent(inout) :: h    !< The task's handle.
   class(*),                 intent(inout) :: data !< A field_t.
   integer                                 :: pass !< Pass.
   integer                                 :: n    !< Values.

   select type (data)
   type is (field_t)
      n = size(data%v)
      do pass = 1, 200
         if (h%cancelled()) return                         ! a safe point, between two passes
         data%v(2:n - 1) = 0.25_real64 * (data%v(1:n - 2) + 2.0_real64 * data%v(2:n - 1) + data%v(3:n))
         call h%report(real(pass, real64) / 200.0_real64, 'smoothing')
      enddo
   endselect
   endsubroutine smooth_field
endmodule tut06_work_task

!< tut06_work, tutorial chapter 6: running work without freezing the window.
program tut06_work
!< tut06_work, tutorial chapter 6: running work without freezing the window.
!<
!< A tool started from a button, its output in a log view; a computation of the program run as a task, with its
!< progress in a progress bar and its end in a notification. The tool is this program itself, started again with
!< `--tool`, so that the tutorial runs on every system.
use, intrinsic :: iso_fortran_env, only : int32, output_unit, real64
use figure, only : app_object, ig_begin, ig_begin_disabled, ig_button, ig_end, ig_end_disabled, ig_same_line, &
                   ig_progress_bar, ig_set_next_window, ig_text, log_view_object, process_object, task_object
use tut06_work_task, only : field_t, smooth_field

implicit none
type(app_object)              :: app      !< Application.
type(process_object)          :: tool     !< The tool.
type(log_view_object)         :: output   !< What it prints.
type(task_object)             :: smoother !< The computation.
type(field_t)                 :: field    !< Its field.
class(*), allocatable         :: data     !< The field given back.
character(len=:), allocatable :: lines(:) !< New lines.
character(len=:), allocatable :: msg      !< Progress message.
character(len=512)            :: me       !< This program.
character(len=16)             :: arg      !< Its first argument.
character(len=48)             :: status   !< The task's status line.
real(real64)                  :: fraction !< Progress.
integer                       :: i        !< Counter.
logical                       :: started  !< The tool was started.

call get_command_argument(0, me)
call get_command_argument(1, arg)
if (trim(arg) == '--tool') then
   call grid_check()
   stop
endif
started = .false.
status = 'not smoothed yet'
field%v = [(merge(1.0_real64, 0.0_real64, mod(i, 1000) < 500), i = 1, 200000)] ! a square wave
call app%init('FIGURE: running work', 640_int32, 400_int32)
do while (app%next_frame())
   call ig_set_next_window(10.0_real64, 10.0_real64, 620.0_real64, 380.0_real64)
   if (ig_begin('Work')) then
      call ig_begin_disabled(smoother%running())
      if (ig_button('Smooth the field')) call smoother%start(smooth_field, field) ! a copy of field goes to the task
      call ig_end_disabled()
      call ig_same_line()
      if (smoother%running()) then
         call smoother%progress(fraction, msg)
         call ig_progress_bar(fraction, label=msg, width=300.0_real64) ! fraction < 0 before the first report
      else
         if (smoother%done()) then
            call smoother%result(data)                     ! given back without a copy
            select type (data)
            type is (field_t)
               call move_alloc(data%v, field%v)
            endselect
            write(status, '(A,F6.4)') 'smoothed: value 500 is ', field%v(500)
            call app%notify('The field is smoothed', kind='success') ! seen even if the user looks elsewhere
         endif
         call ig_text(trim(status))
      endif
      call ig_begin_disabled(tool%running())
      if (ig_button('Check the grid')) then
         call tool%start([character(len=512) :: me, '--tool'])
         started = .true.
      endif
      call ig_end_disabled()
      if (started) then
         call tool%poll(lines)
         call output%add(lines)
      endif
      call output%draw('output')
   endif
   call ig_end()
enddo
call app%destroy()

contains
   subroutine grid_check()
   !< The tool: a check of the blocks of a grid.
   integer(int32) :: b !< Block.

   do b = 1_int32, 24_int32
      write(output_unit, '(A,I0,A,I0,A)') 'block ', b, ': ', 32768_int32 * (1_int32 + mod(b, 3_int32)), &
                                          ' cells, Jacobian positive'
   enddo
   write(output_unit, '(A)') 'grid check: 24 blocks, no error'
   flush(output_unit)
   endsubroutine grid_check
endprogram tut06_work
A window with two buttons: Smooth the field, then Check the grid; a progress bar beside the first fills while the task runs and gives way to the smoothed value, and a notification in the corner says the field is smoothed; the tool's lines fill the log view and end with grid check: 24 blocks, no error
docs/examples/src/tut06_work.F90

A tool from a button ​

fortran
call ig_begin_disabled(tool%running())
if (ig_button('Check the grid')) then
   call tool%start([character(len=512) :: me, '--tool'])
   started = .true.
endif
call ig_end_disabled()
if (started) then
   call tool%poll(lines)
   call output%add(lines)
endif
call output%draw('output')
  • tool%start(args) starts the program args(1) with its arguments: an array, passed as it is, without a shell. The tool here is the program itself, started again with --tool, so that the chapter runs on every system: me is the program's own path, from get_command_argument(0, me), and the program runs its tool part when its first argument is --tool (the whole program: tut06_work.F90). Yours is ['overset', '-i', 'grid.inp'] or ['sbatch', 'case.sh'].
  • ig_begin_disabled(tool%running()) greys the button out while the tool runs: one object runs one process at a time.
  • FIGURE reads the tool's output on a thread of its own as the tool writes, and wakes the frame loop (Waking the loop): the window does not freeze, and the tool never waits for the program.
  • tool%poll(lines), every frame once the tool was started (started), gives the complete lines printed since the last poll; before the first start a poll is a failure (FIG_ERR_STATE), which stops a program that passes no stat (Statuses). output%add(lines) appends them to a log_view_object, and output%draw('output') draws the lines in view, following the end.
  • A tool still running when the program ends is stopped with it. A run that must outlive the program is started with detached=.true. and a log_file.

A computation as a task ​

The program's own long computations run as tasks: a Fortran procedure on a thread of its own. The work is a module procedure with a fixed interface, declared recursive, as is every procedure it calls, since two tasks may run it at once (Tasks); its data is any type, here a field to smooth:

fortran
type :: field_t
   !< A field of values, given to the task and given back smoothed.
   real(real64), allocatable :: v(:) !< Values.
endtype field_t

contains
   recursive subroutine smooth_field(h, data)
   !< Smooth the field 200 times, reporting each pass.
   type(task_handle_object), intent(inout) :: h    !< The task's handle.
   class(*),                 intent(inout) :: data !< A field_t.
   integer                                 :: pass !< Pass.
   integer                                 :: n    !< Values.

   select type (data)
   type is (field_t)
      n = size(data%v)
      do pass = 1, 200
         if (h%cancelled()) return                         ! a safe point, between two passes
         data%v(2:n - 1) = 0.25_real64 * (data%v(1:n - 2) + 2.0_real64 * data%v(2:n - 1) + data%v(3:n))
         call h%report(real(pass, real64) / 200.0_real64, 'smoothing')
      enddo
   endselect
   endsubroutine smooth_field
fortran
call ig_begin_disabled(smoother%running())
if (ig_button('Smooth the field')) call smoother%start(smooth_field, field) ! a copy of field goes to the task
call ig_end_disabled()
call ig_same_line()
if (smoother%running()) then
   call smoother%progress(fraction, msg)
   call ig_progress_bar(fraction, label=msg, width=300.0_real64) ! fraction < 0 before the first report
else
   if (smoother%done()) then
      call smoother%result(data)                     ! given back without a copy
      select type (data)
      type is (field_t)
         call move_alloc(data%v, field%v)
      endselect
      write(status, '(A,F6.4)') 'smoothed: value 500 is ', field%v(500)
      call app%notify('The field is smoothed', kind='success') ! seen even if the user looks elsewhere
   endif
   call ig_text(trim(status))
endif
  • smoother%start(smooth_field, field) runs smooth_field on a worker thread, on a copy of field: the program's own field is not touched while the task runs.
  • Inside the task, h%report(fraction, message) posts the progress and wakes the frame loop; h%cancelled() is the safe point where the task returns if the program asked it to stop (smoother%cancel()).
  • Every frame the program reads the progress (smoother%progress) and draws it with ig_progress_bar(fraction, label=msg): before the task's first report fraction is negative, and the bar is indeterminate (a sliding band).
  • Once smoother%done(), it takes the field back with smoother%result(data), without a copy, and select type gives it its type again; app%notify('The field is smoothed', kind='success') tells the user, in the corner of the window, even if they were looking at the log.
  • A task never draws: no ig_* or ip_* call inside smooth_field. Only the main thread draws; FIGURE refuses a drawing call from a task (the threading rule).
  • nvfortran: compile a program with tasks with -mp, which makes nvfortran's Fortran I/O thread-safe (Known issues); gfortran and ifx need nothing.

What you learned

A program started from the program, its output followed in a log view; a computation run as a task, its progress in a progress bar and its end in a notification; and why the window does not freeze. Reference: Processes and tasks, Progress bars, Notifications.

Next: part two, 7. Building and running the studio: one application, a solver studio, grown chapter by chapter, and how to build and run each chapter's program.

Released under the MIT licence.