12.8 control.job - A common job descriptor for control modules

Module: control.job ¶

This module provides a job record type, a lightweight structure to be used in the control flow subsystems (control.* modules). Currently the only user is control.thread-pool, but some other modules are planned to use job records.

A job record may be returned to an application by other control.* modules so that the application can keep track of the job. It’s not meant for general use, however. An application isn’t supposed to create a new job, or to modify its content; it can just query the job’s properties.

In this section we only describe procedures an application needs to know. The interface for control subsystems is still fluid and may be changed as more subsystems are developed.

Different control flow subsystems may use job structure differently. This section only describes the common properties. Check the individual control flow module to know how to handle returned job objects.

Record type: job ¶

{control.job} A record type denotes the job. Applications should treat it as an opaque structure.

Function: job? obj ¶

{control.job} Returns #t iff obj is a job record, #f otherwise.

Function: job-status job ¶

{control.job} Returns the status of the job. It may be either one of the followings.

#f

Newborn or orphaned job. Usually an application won’t see a job in this status.

acknowledged

A job is recognized by a control flow library, but haven’t yet been run.

running

A job is being processed.

done

A job is finished. An application can retrieve its result by job-result.

error

A job is terminated by an error. An application can retrieve the error causing condition by job-result.

killed

A job is killed by external force. An application can retrieve the reason of kill (which is specific to a particular control flow subsystem) by job-result.

Function: job-result job ¶

{control.job} If the job is in done status, it returns the result of the job. If the job is in error status, it returns the condition object that describes the error. If the job is in killed status, it returns an object describing the reason of kill. The details of the object depends on a particular control flow library. Calling job-result on a job in any other status may return anything; you can’t rely on the result.

Function: job-wait job :optional timeout timeout-val ¶

{control.job} Suspends the calling thread until the job becomes either done, error or killed status. If the job is already in one of those status, it returns immediately. Returns job’s status.

If timeout is given and not #f, it must be a valid timeout spec (a <time> object that represents an absolute time point, or a real number that represents a relative time in seconds.) The meaning of timeout is the same as in mutex-unlock! (see Synchronization primitives). Once the timeout reaches, job-wait returns no matter how the job’s status is, and returns the value specified to timeout-val, which defaults to #f.

Depending on the control flow subsystem, jobs created by it may not be waitable; check out each subsystem’s documentation for the details.

Function: job-acknowledge-time job ¶

Function: job-start-time job ¶

Function: job-finish-time job ¶

{control.job} If the control flow subsystem keeps track of timestamps, these procedure returns the time (in <time> objects) when the job is acknowledged, started and finished (either normally, or abnormally by an error or by being killed). If the job hasn’t reached to certain status, #f is returned instead.

If the subsystem does not track timestamps, these procedures always returns #f.