Skip to content

figure_task ​

figure_task, background tasks: Fortran procedures run on a worker thread, with progress and cooperative cancel.

A task runs work(h, data) on a thread of its own while the frame loop goes on: t%start(work, data), then every frame t%progress(fraction, message) and t%done(); once done, t%result(data). Inside work, h%report posts progress (and wakes the frame loop), h%cancelled() tells whether the program asked it to stop, h%fail reports a failure.

The threading rule: a task computes and reads its own files; it never calls FIGURE's drawing procedures, since Dear ImGui is single-threaded. FIGURE's drawing entry points (app%next_frame, ig_begin/ig_end, the child regions, side bars, menu bars, popups, tab bars, tables, trees and headers, plots and subplots, dock spaces, textures, log%draw) refuse such a call from a worker: they return at once, the task's status becomes FIG_ERR_STATE (given by t%result) and the task is asked to stop.

Source: src/lib/figure_task.F90

Dependencies

Contents ​

Derived Types ​

task_handle_object ​

What a running task knows of itself: given to its work procedure.

Components

NameTypeAttributesDescription
idinteger(kind=c_int)Native handle.

Type-Bound Procedures

NameAttributesDescription
reportpass(self)Post progress.
cancelledpass(self)The program asked the task to stop.
failpass(self)Report a failure.

task_record ​

What the worker thread reaches: the procedure, the data, the handle (at a fixed address while it runs).

Components

NameTypeAttributesDescription
workprocedure(task_work)pointer, nopassThe work.
dataclass(*)allocatableIts data.
handletype(task_handle_object)Its handle.

task_object ​

A procedure of the program run on a worker thread. Not to be copied. An object that ends while its task runs asks the task to stop and waits for it (until its next safe point).

Components

NameTypeAttributesDescription
rectype(task_record)pointerThe running task's record.
idinteger(kind=c_int)Native handle (0: none).

Type-Bound Procedures

NameAttributesDescription
startpass(self)Start a task.
runningpass(self)It runs.
donepass(self)It has ended (its result is waiting).
progresspass(self)Its last progress and message.
cancelpass(self)Ask it to stop.
resultpass(self)Its data, once done.

Subroutines ​

task_trampoline ​

The worker thread's entry: the task's work on its data.

Attributes: recursive

fortran
subroutine task_trampoline(arg)

Arguments

NameTypeIntentAttributesDescription
argtype(c_ptr)valueThe task's record.

handle_report ​

Post the progress, fraction of the work done in [0, 1] (clamped), and a message (absent: the previous one stays); the frame loop is woken to show it. Cheap: call it as often as useful, a few times a second is plenty.

Attributes: recursive

fortran
subroutine handle_report(self, fraction, message)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_handle_object)inHandle.
fractionreal(kind=real64)inDone, in [0, 1].
messagecharacter(len=*)inoptionalWhat is being done.

Call graph

handle_fail ​

Report a failure (a file that cannot be read): t%result gives FIG_ERR_FAILED and message. The task should then return; the first failure is kept.

Attributes: recursive

fortran
subroutine handle_fail(self, message)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_handle_object)inHandle.
messagecharacter(len=*)inWhat failed.

Call graph

task_start ​

Run work(h, data) on a worker thread. data (any type: a file name, an extended type with the arrays to fill) is copied into the task, which works on its copy; t%result gives it back without a copy. Statuses: FIG_ERR_STATE while this object's task runs (a finished one whose result was not taken is discarded) or when called from a task, FIG_ERR_FAILED when no thread can be created. The same in every mode.

fortran
subroutine task_start(self, work, data, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inoutTask.
workprocedure(task_work)The work.
dataclass(*)inIts data.
statinteger(kind=int32)outoptionalStatus.

Call graph

task_progress ​

The last progress the task reported: fraction in [0, 1] (-1 before its first report or before start) and its message ('' if none).

fortran
subroutine task_progress(self, fraction, message)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inTask.
fractionreal(kind=real64)outDone, in [0, 1].
messagecharacter(len=:)outallocatable, optionalWhat is being done.

Call graph

task_cancel ​

Ask the task to stop: it does at its next safe point (h%cancelled()); nothing is stopped mid-write. t%done() tells when it has. FIG_ERR_STATE before start.

fortran
subroutine task_cancel(self, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inoutTask.
statinteger(kind=int32)outoptionalStatus.

Call graph

task_result ​

The task's data once it has ended, moved out (no copy); the object is then free for another start. Statuses: FIG_ERR_STATE before start or while it runs (data not allocated), and for a task that called a drawing procedure; FIG_ERR_FAILED for a task that reported a failure (h%fail): data is given as the task left it, and figure_last_error() gives the message. A cancelled task is not a failure.

fortran
subroutine task_result(self, data, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inoutTask.
dataclass(*)outallocatableIts data.
statinteger(kind=int32)outoptionalStatus.

Call graph

release ​

Forget the task: a running one is asked to stop and waited for.

fortran
subroutine release(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inoutTask.

Call graph

task_final ​

The object ends: its task, if running, is asked to stop and waited for.

fortran
subroutine task_final(self)

Arguments

NameTypeIntentAttributesDescription
selftype(task_object)inoutTask.

Call graph

Functions ​

handle_cancelled ​

True once the program asked the task to stop (t%cancel, the object's end, a refused drawing call): return from work at this safe point, leaving data consistent.

Attributes: recursive

Returns: logical

fortran
function handle_cancelled(self) result(cancelled)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_handle_object)inHandle.

Call graph

task_running ​

True while the task runs (false before start, once it has ended, after result).

Returns: logical

fortran
function task_running(self) result(running)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inTask.

Call graph

task_done ​

True once the task has ended (finished, cancelled or failed) and its result waits for t%result; false before start, while it runs, and after result.

Returns: logical

fortran
function task_done(self) result(done)

Arguments

NameTypeIntentAttributesDescription
selfclass(task_object)inTask.

Call graph

Released under the MIT licence.