multisession: Create a multisession future whose value will be resolved...
In future: Unified Parallel and Distributed Processing in R for Everyone

multisession

R Documentation

Create a multisession future whose value will be resolved asynchronously in a parallel R session

Description

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.

Usage

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

Arguments

`...`	Additional arguments passed to `Future()`.
`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.
`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.

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.

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).

Examples



## 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)

v <- value(f)
print(v)
stopifnot(v == 0)

## Explicitly close multisession workers by switching plan
plan(sequential)

future documentation built on Sept. 11, 2024, 7:35 p.m.