
Create a multisession future whose value will be resolved asynchronously in a parallel R session
Source:R/backend_api-13.MultisessionFutureBackend-class.R
multisession.Rd
WARNING: This function must never be called.
It may only be used with plan()
Usage
multisession(
...,
workers = availableCores(constraints = "connections-16"),
rscript_libs = .libPaths()
)
Arguments
- workers
The number of parallel processes to use. If a function, it is called without arguments when the future is created and its value is used to configure the workers. If
workers == 1
, then all processing using done in the current/main R session and we therefore fall back to using a sequential future. To override this fallback, useworkers = I(1)
.- 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, useplan(multisession, ..., rscript_libs = NULL)
. Important: Note that the library path is set on the workers when they are created, i.e. whenplan(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 toparallelly::makeClusterPSOCK()
.- ...
Additional arguments passed to
Future()
.
Value
A MultisessionFuture.
If workers == 1
, then all processing is done in the
current/main R session and we therefore fall back to using a
lazy future. To override this fallback, use workers = I(1)
.
Details
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.
This function is must not 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)
# }