Functions for retrieving results from a job queue

Share:

Description

Q.collect returns the queue's first available result in a standardized format. Q.pop is a simplified version of Q.collect that returns the pure result without any further information. Q.collect.all and Q.pop.all return all results that are currently available in the queue. Q.isready returns TRUE if there is a result available in the queue, FALSE otherwise.

Usage

1
2
3
4
5
6
7
Q.collect(Q, tag = NULL, wait = TRUE)
Q.pop(Q, tag = NULL, wait = TRUE)

Q.collect.all(Q, tag = NULL)
Q.pop.all(Q, tag = NULL)

Q.isready(Q, write = FALSE, timeout = 0)

Arguments

Q

A job queue as created by Q.make.

tag

Setting tag will cause Q.collect or Q.pop to return the first available result with the corresponding tag. Setting tag for Q.collect.all or Q.pop.all will return all available results with that tag.

wait

Maximum total time to wait until a result becomes available (in seconds). Logical values TRUE/FALSE are coerced to 1/0, respectively. Setting wait=Inf will hang if no result ever becomes available.

write

Set write=TRUE to test if available for writing. Queue should always be available for writing. write=FALSE tests if there is a result available in the queue.

timeout

Time to wait (in seconds) for the socket to respond.

Details

Q.collect returns a list containing the result at entry $value. The return value always contains a boolean entry $has.result which is FALSE if there was no result to be read (either because queue has not been tasked with anything or no result is ready for pick-up yet), TRUE otherwise. If a result could be read from the socket, then the return value contains the entry $success which is FALSE if the computation produced an error. Furthermore, if the job was sent with values for tag and tranche, then the result contains these values at entries $tag and $tranche.

Q.collect discards muted results and returns the first available non-muted result. Setting tag will cause Q.collect to return the first available result with the corresponding tag. If no result with this tag becomes available within the waiting time, then the result's has.result field is FALSE. If you set a tag, make sure wait is not set to 0/FALSE to give the queue time to sieve through the available results.

Q.pop is a simple version of Q.collect that only returns the result (without has.result, tag, tranche, etc.). Note: a NULL return value may either mean that the return value was NULL or that there was no result available at this time. Use Q.collect if you need to tell the difference.

Q.collect.all and Q.pop.all return all results that are currently available in the queue. There is no wait parameter as this would be practically equivalent to a construction like Sys.sleep(wait); Q.collect.all(Q).

There is usually no need to use Q.isready since Q.collect's has.result field indicates whether the queue was ready.

Value

Q.collect returns a list which is guaranteed to have a logical field has.result. If has.result=TRUE, then the result also has a logical field success indicating whether or not an error occurred, and a field value containing the actual job result.

Q.pop simply returns the value field of Q.collect.

Q.collect.all and Q.pop.all return lists of elements in the respective formats.

Q.isready returns logical.

Note

If tag is specified for any of the retrieval functions, then available results with different tags will still be retrieved from the socket but stored in Q$data$rack for later retrieval from the queue. This is handled automatically by the queue.

Author(s)

Bastian Laubner

See Also

Q.make, as well as Q.push and jobqueue for further examples.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
Q = Q.make()
Q.push(Q, "Some job")

# safe way to check if the job returned a value
job = Q.collect(Q)
if (job$has.result) {
  # do something with the result
  print(job$value)
}

# safe way with error checking
if (job$has.result) {
  if (job$success) {
    # do something with the job result
    print(job$value)
  } else {
    # an error occurred during processing, error message in job$value
    stop(job$value)
  }
}

Q.close(Q)