Skip to content

15. Heavy work off the frame ​

Until now the studio read field.dat inside a frame: for 48 x 32 nodes nobody notices. The example case fine has 900 x 600 nodes and a 7 MB result; a production solver's are gigabytes, often on a network file system. Read inside a frame, they freeze the window: no redraw, no answer to the mouse, the close button ignored. The studio now reads the result as a task, a Fortran procedure run on a worker thread, and draws its progress meanwhile.

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

The whole program: tut15_task.F90. --examples now also writes the fine case and runs the solver on it once (a few seconds), so that its large result exists. On this machine its 540 000 values read in a tenth of a second: the recording shows the progress for a few frames only.

What this chapter adds to chapter 14's program, tut14_view3d.F90:

  • read_field: Read a field.dat row by row, reporting the progress, stopping if asked; then make the coarse copy
  • follow_load: Every frame
  • take_field: Take the field the task read (no copy), or tell why there is none
  • run_solver: The solver run on the case dir to its end, with no shell (the same on every platform); its log, written in the case, removed after
  • changed: build_3d, draw_profile, draw_result, draw_status, draw_studio, load_field, write_examples

The work ​

fortran
type :: field_t
   !< A field to read: the file, given to the task; the values and a coarser copy, given back.
   character(len=:), allocatable :: file              !< The solver's field.dat.
   real(real64)                  :: lx = 0.0_real64   !< The plate [m].
   real(real64)                  :: ly = 0.0_real64
   real(real64), allocatable     :: values(:,:)       !< The field, every node.
   real(real64), allocatable     :: coarse(:,:)       !< Every stride-th node, to draw.
   integer(int32)                :: stride = 1_int32  !< The coarse copy's stride.
endtype field_t

contains
   recursive subroutine read_field(h, data)
   !< Read a field.dat row by row, reporting the progress, stopping if asked; then make the coarse copy.
   type(task_handle_object), intent(inout) :: h      !< The task's handle.
   class(*),                 intent(inout) :: data   !< A field_t.
   character(len=256)                      :: iomsg  !< The run time's message.
   integer(int32)                          :: nx, ny !< The grid.
   integer(int32)                          :: j      !< Row.
   integer(int32)                          :: u      !< Unit: the task's own.
   integer(int32)                          :: ios    !< Status.

   select type (data)
   type is (field_t)
      open(newunit=u, file=data%file, status='old', action='read', iostat=ios, iomsg=iomsg)
      if (ios /= 0) then
         call h%fail(trim(iomsg))                    ! t%result gives FIG_ERR_FAILED and this message
         return
      endif
      read(u, *, iostat=ios, iomsg=iomsg)            ! the comment line
      if (ios == 0) read(u, *, iostat=ios, iomsg=iomsg) nx, ny, data%lx, data%ly
      if (ios == 0) then
         allocate(data%values(nx, ny))
         do j = 1_int32, ny
            if (h%cancelled()) exit                  ! a safe point, between two rows
            read(u, *, iostat=ios, iomsg=iomsg) data%values(:, j)
            if (ios /= 0) exit
            if (mod(j, 8_int32) == 0_int32) call h%report(real(j, real64) / ny, 'reading field.dat')
         enddo
      endif
      close(u)
      if (ios /= 0) then
         call h%fail(data%file//': '//trim(iomsg))
         return
      endif
      if (h%cancelled()) return
      data%stride = (max(nx, ny) - 1_int32) / MAX_SHOWN + 1_int32
      data%coarse = data%values(1::data%stride, 1::data%stride) ! what is drawn: at most MAX_SHOWN a side
   endselect
   endsubroutine read_field
  • The task's procedure is a module procedure with the interface task_work, subroutine work(h, data). It runs on another thread, so it cannot be an internal procedure of the program: those reach the program's variables through the main thread's stack (Tasks).
  • It is recursive, as is every procedure it calls: two tasks may run the same code at once.
  • data is the task's own copy of what the program gave it, here a field_t holding the file's name; the task fills the same object with the values and gives it back.
  • h%report(fraction, message) posts the progress and wakes the frame loop; h%cancelled() is the safe point, between two rows, where the task returns if the program asked it to stop; h%fail(message) reports a failure.
  • The task opens its own unit (newunit=): Fortran I/O is safe on a worker as long as no other thread uses the same unit (What code is safe on a worker).
  • It also makes the coarse copy that is drawn: every stride-th node, at most 200 a side. A heatmap of 540 000 cells, or a surface of a million triangles, would be redrawn in every frame the user moves the mouse; 180 x 120 are not. The profile and the probes keep reading the full field.

Starting it, following it ​

fortran
if (loader%running()) then
   call app%notify('A field is being read: open the case again when it is done', kind='warning')
   return
endif
if (loader%done()) call take_field()              ! a result not taken yet: taken, then replaced
request%file = case_dir//'/field.dat'
call loader%start(read_field, request, stat=stat) ! the task gets a copy of request
if (stat /= FIG_OK) call app%notify(figure_last_error(), kind='error')
show_result = .true.                              ! the Result panel shows the progress

loader%start(read_field, request) runs read_field on a worker, on a copy of request, and returns at once. One task_object runs one task at a time: a second open while it reads is refused with a word to the user.

fortran
if (loader%running()) then                        ! every frame while it reads: the window never waits for it
   call loader%progress(fraction, msg)
   call ig_progress_bar(fraction, label=msg, width=300.0_real64)
   call ig_same_line()
   if (ig_button(ICON_SQUARE//' Stop')) then
      load_cancelled = .true.
      call loader%cancel()                        ! the task stops at its next safe point
   endif
   return
endif

Every frame, while the task runs, the Result panel draws its progress (loader%progress(fraction, message)) and a Stop button: loader%cancel() asks it to stop at its next safe point. Before its first report the fraction is negative and the bar slides to and fro.

fortran
call loader%result(data, stat=stat)               ! moved out of the task; the task object is free again
if (stat /= FIG_OK) then
   call app%notify('field.dat does not read: '//figure_last_error(), kind='error') ! h%fail's message
   return
endif
if (load_cancelled) then                          ! what was read is left as it was: not shown
   load_cancelled = .false.
   call app%notify('Reading field.dat was stopped', kind='warning')
   return
endif
select type (data)
type is (field_t)
   call move_alloc(data%values, field)
   call move_alloc(data%coarse, coarse)
   flx = data%lx
   fly = data%ly
   stride = data%stride
endselect
  • Once loader%done(), loader%result(data) moves the task's data out, without a copy, and frees the object for the next task. select type gives it its type again, and move_alloc hands the arrays to the program, again without a copy.
  • A task that called h%fail gives FIG_ERR_FAILED with its message in figure_last_error().
  • A cancelled task is done like a finished one; the studio knows it asked, and drops what was read.

The rule: only the main thread draws ​

The task reads and computes; it never calls a drawing procedure (ig_*, ip_*, view%draw). Dear ImGui is not thread-safe, and FIGURE refuses a drawing call from a task: the call returns at once, the task is asked to stop, and loader%result gives FIG_ERR_STATE naming the procedure (The threading rule). Everything the user sees is drawn by the main thread, from what the task gave back.

What you learned

A task: a recursive module procedure working on its own copy of the data, with progress, a safe point to stop and a failure message; started from the frame loop, followed every frame, its result moved out without a copy; why a task never draws; and a coarse copy for drawing a fine field. Reference: Processes and tasks, Progress bars, Known issues: tasks.

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

Next: 16. Robustness: checking the input, reporting every failure.

Released under the MIT licence.