The value of a future or the values of all elements in a container

Gets the value of a future or the values of all elements (including futures) in a container such as a list, an environment, or a list environment. If one or more futures is unresolved, then this function blocks until all queried futures are resolved.

value(...)

# S3 method for class 'Future'
value(future, stdout = TRUE, signal = TRUE, drop = FALSE, ...)

# S3 method for class 'list'
value(
  x,
  idxs = NULL,
  recursive = 0,
  reduce = NULL,
  stdout = TRUE,
  signal = TRUE,
  interrupt = TRUE,
  inorder = TRUE,
  drop = FALSE,
  force = TRUE,
  sleep = getOption("future.wait.interval", 0.01),
  ...
)

# S3 method for class 'listenv'
value(
  x,
  idxs = NULL,
  recursive = 0,
  reduce = NULL,
  stdout = TRUE,
  signal = TRUE,
  interrupt = TRUE,
  inorder = TRUE,
  drop = FALSE,
  force = TRUE,
  sleep = getOption("future.wait.interval", 0.01),
  ...
)

# S3 method for class 'environment'
value(x, ...)

Arguments

future, x: A Future, an environment, a list, or a list environment.
stdout: If TRUE, standard output captured while resolving futures is relayed, otherwise not.
signal: If TRUE, conditions captured while resolving futures are relayed, otherwise not.
drop: If TRUE, resolved futures are minimized in size and invalidated as soon the as their values have been collected and any output and conditions have been relayed. Combining drop = TRUE with inorder = FALSE reduces the memory use sooner, especially avoiding the risk of holding on to future values until the very end.
idxs: (optional) integer or logical index specifying the subset of elements to check.
recursive: A non-negative number specifying how deep of a recursion should be done. If TRUE, an infinite recursion is used. If FALSE or zero, no recursion is performed.
reduce: An optional function for reducing all the values. Optional attribute init can be used to set initial value for the reduction. If not specified, the first value will be used as the initial value. Reduction of values is done as soon as possible, but always in the same order as x, unless inorder is FALSE.
interrupt: If TRUE and signal is TRUE, non-resolved futures are interrupted as soon as an error is detected in one of the futures, before signaling the error.
inorder: If TRUE, then standard output and conditions are relayed, and value reduction, is done in the order the futures occur in x, but always as soon as possible. This is achieved by buffering the details until they can be released. By setting inorder = FALSE, no buffering takes place and everything is relayed and reduced as soon as a new future is resolved. Regardlessly, the values are always returned in the same order as x.
force: (internal) If TRUE, captured standard output and captured conditions already relayed is relayed again, otherwise not.
sleep: Number of seconds to wait before checking if futures have been resolved since last time.
...: All arguments used by the S3 methods.

Value

value() of a Future object returns the value of the future, which can be any type of R object.

value() of a list, an environment, or a list environment returns an object with the same number of elements and of the same class. Names and dimension attributes are preserved, if available. All future elements are replaced by their corresponding value() values. For all other elements, the existing object is kept as-is.

If signal is TRUE and one of the futures produces an error, then that error is relayed.

Examples

## ------------------------------------------------------
## A single future
## ------------------------------------------------------
x <- sample(100, size = 50)
f <- future(mean(x))
v <- value(f)
message("The average of 50 random numbers in [1,100] is: ", v)
#> The average of 50 random numbers in [1,100] is: 50



## ------------------------------------------------------
## Ten futures
## ------------------------------------------------------
xs <- replicate(10, { list(sample(100, size = 50)) })
fs <- lapply(xs, function(x) { future(mean(x)) })

## The 10 values as a list (because 'fs' is a list)
vs <- value(fs)
message("The ten averages are:")
#> The ten averages are:
str(vs)
#> List of 10
#>  $ : num 48.8
#>  $ : num 50.7
#>  $ : num 48.6
#>  $ : num 54.3
#>  $ : num 49.1
#>  $ : num 46.5
#>  $ : num 48.4
#>  $ : num 49.8
#>  $ : num 47.1
#>  $ : num 50.2

## The 10 values as a vector (by manually unlisting)
vs <- value(fs)
vs <- unlist(vs)
message("The ten averages are: ", paste(vs, collapse = ", "))
#> The ten averages are: 48.84, 50.68, 48.56, 54.3, 49.1, 46.52, 48.42, 49.76, 47.12, 50.24

## The values as a vector (by reducing)
vs <- value(fs, reduce = `c`)
message("The ten averages are: ", paste(vs, collapse = ", "))
#> The ten averages are: 48.84, 50.68, 48.56, 54.3, 49.1, 46.52, 48.42, 49.76, 47.12, 50.24

## Calculate the sum of the averages (by reducing)
total <- value(fs, reduce = `sum`)
message("The sum of the ten averages is: ", total)
#> The sum of the ten averages is: 493.54