-
Notifications
You must be signed in to change notification settings - Fork 83
/
future-5-startup.md.rsp
85 lines (58 loc) · 2.98 KB
/
future-5-startup.md.rsp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
<%@meta language="R-vignette" content="--------------------------------
%\VignetteIndexEntry{A Future for R: Controlling Default Future Strategy}
%\VignetteAuthor{Henrik Bengtsson}
%\VignetteKeyword{R}
%\VignetteKeyword{package}
%\VignetteKeyword{vignette}
%\VignetteKeyword{future}
%\VignetteKeyword{promise}
%\VignetteEngine{R.rsp::rsp}
%\VignetteTangle{FALSE}
--------------------------------------------------------------------"%>
<%
library(R.utils)
`%<-%` <- future::`%<-%`
options("withCapture/newline" = FALSE)
%>
# <%@meta name="title"%>
The default is to use synchronous futures, but this _default_ can be overridden via R options, system environment variables and command-line options as explained below as well as in `help("future.options", package = "future")`.
## R options
The default strategy for resolving futures can be controlled via R option `future.plan`. For instance, if we add
```r
options(future.plan = "multisession")
```
to our `~/.Rprofile` startup script, the future package will resolve futures in parallel (asynchronously using all available cores), i.e.
```sh
$ Rscript -e "class(future::plan())"
[1] "multisession" "future" "function"
```
Option `future.plan` is ignored if command-line option `--parallel` (`-p`) is specified.
## Environment variables
An alternative to using `options()` for setting option `future.plan` is to specify system environment variable `R_FUTURE_PLAN`. If set, then the future package will set `future.plan` accordingly _when loaded_. For example,
```sh
$ export R_FUTURE_PLAN=multisession
$ Rscript -e "class(future::plan())"
[1] "multisession" "future" "function"
```
Environment variable `R_FUTURE_PLAN` is ignored if either option `future.plan` or command-line option `--parallel` (`-p`) is specified.
## Command-line options
When loaded, the future package checks for the command-line option `--parallel=ncores` (short `-p ncores`) and sets the future strategy (via option `future.plan`) and the number of available cores (via option `mc.cores`) accordingly. This provides a convenient mechanism for specifying parallel future processing from the command line. For example, if we start R with
```sh
$ R --quiet --args --parallel=2
```
then future will interpret this as we wish to resolve futures in parallel using 2 cores. More specifically, we get that
```r
> availableCores()
mc.cores
2
> class(future::plan())
[1] "FutureStrategy" "tweaked" "multisession" "future" "function"
```
We can use this command-line option also with `Rscript`, which provides a convenient mechanism for launching future-enhanced R scripts such that they run in parallel, e.g.
```sh
$ Rscript analysis.R --parallel=4
```
This does, of course, require that the script uses futures and the future package.
If `--parallel=1` is specified, or equivalently `-p 1`, then futures are resolved using a single process.
Specifying these command-line options override any other startup settings.
[future]: https://cran.r-project.org/package=future