A multisession future is a future that uses multisession evaluation, which means that its value is computed and resolved in parallel in another R session.

multisession(
  ...,
  workers = availableCores(),
  lazy = FALSE,
  rscript_libs = .libPaths(),
  envir = parent.frame()
)

Arguments

...

Additional arguments passed to Future().

workers

A positive numeric scalar or a function specifying the maximum number of parallel futures that can be active at the same time before blocking. If a function, it is called without arguments when the future is created and its value is used to configure the workers. The function should return a numeric scalar.

lazy

If FALSE (default), the future is resolved eagerly (starting immediately), otherwise not.

rscript_libs

A character vector of R package library folders that the workers should use. The default is .libPaths() so that multisession workers inherits the same library path as the main R session. To avoid this, use plan(multisession, ..., rscript_libs = NULL). Important: Note that the library path is set on the workers when they are created, i.e. when plan(multisession) is called. Any changes to .libPaths() in the main R session after the workers have been created will have no effect. This is passed down as-is to parallelly::makeClusterPSOCK().

envir

The environment from where global objects should be identified.

Value

A MultisessionFuture. If workers == 1, then all processing using done in the current/main R session and we therefore fall back to using a lazy future.

Details

This function is not meant to be called directly. Instead, the typical usages are:

# Evaluate futures in parallel on the local machine via as many background
# processes as available to the current R process
plan(multisession)

# Evaluate futures in parallel on the local machine via two background
# processes
plan(multisession, workers = 2)

The background R sessions (the "workers") are created using makeClusterPSOCK().

For the total number of R sessions available including the current/main R process, see parallelly::availableCores().

A multisession future is a special type of cluster future.

See also

For processing in multiple forked R sessions, see multicore futures.

Use parallelly::availableCores() to see the total number of cores that are available for the current R session.

Examples

# \donttest{ ## Use multisession futures plan(multisession) ## A global variable a <- 0 ## Create future (explicitly) f <- future({ b <- 3 c <- 2 a * b * c }) ## A multisession future is evaluated in a separate R session. ## Changing the value of a global variable will not affect ## the result of the future. a <- 7 print(a)
#> [1] 7
v <- value(f) print(v)
#> [1] 0
stopifnot(v == 0) ## Explicitly close multisession workers by switching plan plan(sequential) # }