job-control functions¶

function job-control/jobs¶: display the state of outstanding jobs

function job-control/wait [jobs]¶

loop over jobs waiting for each job in turn to change status

Param jobs:: jobs to wait for, defaults to %idio-jobs
Type jobs:: list of %idio-job, optional
Return:: unspecified

A job’s status changes if it is stopped or completes.

If there are any jobs then do-job-notification will be called when all of the jobs have changed state.

job meta-commands¶

There are a number of words that can precede a job which generally affect the environment the job is run in.

Not all the meta-commands work together.

collect-output collects the output from a job

return:

the stdout of the job

rtype:

string

This is the equivalent of Bash’s Command Substitution, $(...).

fg-job runs the job in the foreground

return:

the boolean status of the job

rtype:

boolean

This is the default and the meta-command exists for completeness.

subshell runs the job in the foreground

return:

the boolean status of the job

rtype:

boolean

This is called by the {{...}} reader form.

bg-job runs the job in the background

return:

#t

This is the equivalent of most shell’s ... &.

pipe-into directs the stdin of the job to the read-end of a pipe(2) and an output pipe handle derived from the write-end of the pipe is returned

return:

output pipe handle from job

rtype:

handle

Whatever the caller writes to this pipe handle will be delivered to the stdin of the job.

This is similar to Perl’s open ("| ...").

named-pipe-into directs the stdin of the job from a named pipe and that pipe name is returned.

return:

named pipe name

rtype:

pathname

The caller is expected to open the returned pipe name for writing.

On many systems the pipe’s name will be /dev/fd/n but on some systems it will be a FIFO in the file system.

This is the equivalent of Bash’s Process Substitution form >(...).

The job is an asynchronous command and if it does not exit with a zero status will raise an ^rt-async-command-status-error.

pipe-from directs the stdout of the job to the write-end of a pipe(2) and an input pipe handle derived from the read-end of the pipe is returned.

return:

input pipe handle to job

rtype:

handle

Whatever the job writes to its stdout can be read by the caller from this pipe handle.

This is similar to Perl’s open ("... |").

named-pipe-from directs the stdout of the job to a named pipe and that pipe name is returned.

return:

named pipe name

rtype:

pathname

The caller is expected to open the returned pipe name for reading.

On many systems the pipe’s name will be /dev/fd/n but on some systems it will be a FIFO in the file system.

This is the equivalent of Bash’s Process Substitution form <(...).

The job is an asynchronous command and if it does not exit with a zero status will raise an ^rt-async-command-status-error.

time flags that a report on the accumulated resources of the job should be produced when the job completes

If the job was backgrounded the reported timings will be wholly inaccurate.

Warning

time will run the supplied command in a subshell which might not be obvious if the supplied command is a regular function call.

Repeated runnings might produce some quirks such as random numbers repeating the same sequence – which is entirely expected as it is simply this instance of Idio continuing multiple times.

Here, a more useful timer might be time-function.

function job-control/cat-file fn¶

return the contents of fn

Param fn:: filename
Type fn:: string

function job-control/do-job-notification¶: notify the user of any job status changes

function job-control/format-job-detail job [args]¶

display a normalised form of job

Param job:: job to report on
Type job:: %idio-job
Param handle:: output handle, defaults to current-output-handle
Type handle:: output handle, optional

The actual form of the report is subject to change and should not be relied on.

Last built at 2024-12-21T07:10:40Z+0000 from 62cca4c (dev) for Idio 0.3.b.6