Skip to content

figure_process ​

figure_process, programs started from the program (process_object) and a view of their output (log_view_object).

A process runs in one of two modes.

  • Captured (the default): its standard output, and its standard error with merge_stderr (the default), are piped to the program. A native reader thread drains the pipe as the child writes and wakes the frame loop, so a child printing megabytes never blocks while the program is busy or its loop sleeps. p%poll(lines) gives the complete lines since the last poll. The child is killed when the object ends, at app%destroy, and when the program exits.
  • Detached (detached=.true., with log_file): its output goes to the file, and the child survives the program. p%poll(lines) follows the file.

The arguments are passed as an array, without a shell: ['sh', '-c', 'a | b'] when a pipeline is wanted.

Source: src/lib/figure_process.F90

Dependencies

Contents ​

Derived Types ​

process_object ​

A program started from the program: p%start(args), then p%poll(lines) every frame while p%running(). Not to be copied: the copy would own the same child.

Components

NameTypeAttributesDescription
idinteger(kind=c_int)Native handle (0: none).

Type-Bound Procedures

NameAttributesDescription
startpass(self)Start a program.
pollpass(self)The complete lines since the last poll.
runningpass(self)It runs (or output is still to be read).
exit_codepass(self)Its exit code (captured, ended).
killedpass(self)It ended after kill.
pidpass(self)Its process id.
killpass(self)Ask it to end.

log_line_object ​

One line of a log view.

Components

NameTypeAttributesDescription
textcharacter(len=:)allocatableThe line.

log_view_object ​

Lines of text kept in a ring buffer (set_cap, default 10000 lines: the oldest go first) and drawn in a region of their own, only those in view. The view follows the end while it is scrolled to the bottom; a click chooses a line, shift+click extends the choice, ctrl+c (cmd+c on macOS) or the right-click menu copies it.

Components

NameTypeAttributesDescription
ringtype(log_line_object)allocatableThe lines, from position head.
capinteger(kind=int32)Lines kept at most.
headinteger(kind=int32)Position of the oldest line in ring.
ninteger(kind=int32)Lines kept.
totalinteger(kind=int64)Lines ever added (the newest's number).
selinteger(kind=int64)First and last chosen line (numbers; 0: none).
followlogicalThe view follows the end.
viewinteger(kind=int32)Kept lines in view on the last draw.

Type-Bound Procedures

NameAttributesDescription
add_linespass(self)Add lines, oldest first (as p%poll gives them).
add_linepass(self)Add a line (trailing blanks removed); with the buffer full, the oldest line goes.
addAdd one line or several. Generic: add_line, add_lines
clearpass(self)Remove every line.
set_cappass(self)The number of lines kept.
countpass(self)Lines kept.
linepass(self)A kept line.
drawpass(self)Draw the view.
followingpass(self)The view follows the end.
in_viewpass(self)The lines in view on the last draw.
copypass(self)The chosen lines, joined by newlines.

Subroutines ​

process_start ​

Start the program args(1) with the arguments args(2:) (each trimmed of trailing blanks; no shell). cwd: its working directory (default: the program's). env: NAME=value entries added to (or replacing in) the program's environment. merge_stderr (default true): standard error goes with standard output (false: captured, it goes to the program's own standard error; detached, it is discarded). detached (default false) needs log_file, which is created or truncated. Statuses: FIG_ERR_STATE while this object's previous process still runs, FIG_ERR_ARGUMENT for an empty args, an entry of env without =, detached without log_file (or log_file without detached), FIG_ERR_FAILED when the program cannot be started (not found, not executable) or the log file cannot be written. The same in every mode (in remote mode the program runs on the server).

fortran
subroutine process_start(self, args, cwd, env, merge_stderr, detached, log_file, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inoutProcess.
argscharacter(len=*)inProgram and arguments.
cwdcharacter(len=*)inoptionalWorking directory.
envcharacter(len=*)inoptionalNAME=value entries.
merge_stderrlogicalinoptionalStandard error with the output (default true).
detachedlogicalinoptionalDetached (default false).
log_filecharacter(len=*)inoptionalDetached: the file of its output.
statinteger(kind=int32)outoptionalStatus.

Call graph

process_poll ​

The complete lines printed since the last poll, oldest first, without their newline (a carriage return is dropped); a last line without a newline is kept until it is completed, or given once the process has ended. lines has no element when there is nothing new; its length is the longest line's (shorter ones are padded with blanks: trim them). Detached: the lines appended to log_file. Status: FIG_ERR_STATE before start.

fortran
subroutine process_poll(self, lines, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inoutProcess.
linescharacter(len=:)outallocatableThe new lines.
statinteger(kind=int32)outoptionalStatus.

Call graph

process_kill ​

Ask the process to end: SIGTERM on POSIX (with force, SIGKILL); on Windows a close request to its windows or console (a console program may ignore it: use force, TerminateProcess). Only the started program is stopped, not the programs it started itself. An ended process: nothing happens. FIG_ERR_STATE before start, FIG_ERR_FAILED when the system refuses.

fortran
subroutine process_kill(self, force, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inoutProcess.
forcelogicalinoptionalAt once (default false).
statinteger(kind=int32)outoptionalStatus.

Call graph

process_final ​

The object ends: a captured process still running is killed; a detached one goes on.

fortran
subroutine process_final(self)

Arguments

NameTypeIntentAttributesDescription
selftype(process_object)inoutProcess.

Call graph

pack_strings ​

The strings of s, trimmed, one after the other, and their lengths.

Attributes: pure

fortran
subroutine pack_strings(s, packed, lens)

Arguments

NameTypeIntentAttributesDescription
scharacter(len=*)inStrings.
packedcharacter(kind=c_char, len=:)outallocatablePacked.
lensinteger(kind=c_int)outallocatableLengths [bytes].

Call graph

split_lines ​

buf cut at each LF (carriage returns dropped); a last piece without LF is a line too.

Attributes: pure

fortran
subroutine split_lines(buf, lines)

Arguments

NameTypeIntentAttributesDescription
bufcharacter(len=*)inBytes.
linescharacter(len=:)outallocatableLines.

Call graph

add_line ​

Add a line (trailing blanks removed); with the buffer full, the oldest line goes.

fortran
subroutine add_line(self, line)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inoutLog.
linecharacter(len=*)inLine.

Call graph

add_lines ​

Add lines, oldest first (as p%poll gives them).

fortran
subroutine add_lines(self, lines)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inoutLog.
linescharacter(len=*)inLines.

Call graph

log_clear ​

Remove every line (and the choice); the cap stays.

fortran
subroutine log_clear(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inoutLog.

log_set_cap ​

Keep at most cap lines (at least 1): the newest stay. Status: FIG_ERR_ARGUMENT for cap < 1.

fortran
subroutine log_set_cap(self, cap, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inoutLog.
capinteger(kind=int32)inLines kept at most.
statinteger(kind=int32)outoptionalStatus.

Call graph

log_in_view ​

The kept lines drawn on the last draw (last < first when none).

Attributes: pure

fortran
subroutine log_in_view(self, first, last)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inLog.
firstinteger(kind=int32)outFirst line in view.
lastinteger(kind=int32)outLast line in view.

log_draw ​

Draw the lines in a region of their own (id, not shown) as wide as the space left and height [pixels] high (absent or 0: the rest of the window; negative: leave that much below). Only the lines in view are drawn. The view follows the end while it is scrolled to the bottom; scrolled up, it stays where it is.

Attributes: recursive

fortran
subroutine log_draw(self, id, height)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inoutLog.
idcharacter(len=*)inId of the region.
heightreal(kind=real64)inoptionalHeight [pixels].

Call graph

Functions ​

process_running ​

True while the process runs; a captured one counts as running until its output has all been read by FIGURE (then a last poll gives the rest). False before start.

Returns: logical

fortran
function process_running(self) result(running)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inProcess.

Call graph

process_exit_code ​

The exit code of a captured process that has ended (after a kill: the negative signal number on POSIX, 1 on Windows). FIG_ERR_STATE (and -1) before start, while it runs, and for a detached process (its exit code is not known: the program's own log tells how it ended).

Returns: integer(kind=int32)

fortran
function process_exit_code(self, stat) result(code)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inProcess.
statinteger(kind=int32)outoptionalStatus.

Call graph

process_killed ​

True when the process ended after kill (false before start, while it runs, or when it ended by itself before the kill).

Returns: logical

fortran
function process_killed(self) result(killed)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inProcess.

Call graph

process_pid ​

The process id given by the system (0 before start).

Returns: integer(kind=int64)

fortran
function process_pid(self) result(pid)

Arguments

NameTypeIntentAttributesDescription
selfclass(process_object)inProcess.

Call graph

log_count ​

The number of lines kept.

Attributes: pure

Returns: integer(kind=int32)

fortran
function log_count(self) result(n)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inLog.

log_line ​

Kept line i, from 1 (the oldest kept) to count(); '' out of range.

Attributes: pure

Returns: character(len=:)

fortran
function log_line(self, i) result(text)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inLog.
iinteger(kind=int32)inLine.

log_following ​

True while the view follows the end (it was scrolled to the bottom on the last draw): new lines scroll it.

Attributes: pure

Returns: logical

fortran
function log_following(self) result(follow)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inLog.

log_copy ​

The chosen lines (with all, every kept line), joined by newlines; '' when none is chosen.

Returns: character(len=:)

fortran
function log_copy(self, all) result(text)

Arguments

NameTypeIntentAttributesDescription
selfclass(log_view_object)inLog.
alllogicalinoptionalEvery line.

Call graph

Released under the MIT licence.