[med-svn] [r-cran-future] 01/01: New upstream version 1.0.1
Michael Crusoe
misterc-guest at moszumanska.debian.org
Thu Nov 10 11:00:02 UTC 2016
This is an automated email from the git hooks/post-receive script.
misterc-guest pushed a commit to annotated tag upstream/1.0.1
in repository r-cran-future.
commit 338d51b5eb72e7677472d7043fb1d66be7719dfb
Author: Michael R. Crusoe <michael.crusoe at gmail.com>
Date: Mon Sep 19 02:57:48 2016 -0700
New upstream version 1.0.1
---
.Rbuildignore | 47 ++
.Rinstignore | 5 +
.covr.R | 27 +
.gitignore | 16 +
.make/Makefile | 475 +++++++++++
.travis.yml | 38 +
DESCRIPTION | 20 +-
MD5 | 150 ----
Makefile | 9 +
NEWS | 16 +
OVERVIEW.md | 14 +
R/Future-class.R | 19 +-
R/FutureError-class.R | 36 +-
R/remote.R | 15 +-
R/signalEarly.R | 4 +-
R/zzz.R | 6 +-
README.md | 655 +++++++++++++++
appveyor.yml | 72 ++
build/vignette.rds | Bin 379 -> 0 bytes
cran-comments.md | 49 ++
incl/cluster.R | 33 +
incl/eager.R | 22 +
incl/future.R | 13 +
incl/futureAssign_OP.R | 32 +
incl/futureOf.R | 33 +
incl/lazy.R | 60 ++
incl/mandelbrot.R | 6 +
incl/multicore.R | 22 +
incl/multiprocess.R | 29 +
incl/multisession.R | 29 +
incl/plan.R | 59 ++
incl/remote.R | 11 +
inst/doc/future-1-overview.html | 881 ---------------------
inst/doc/future-2-issues.html | 447 -----------
inst/doc/future-2-issues.md.rsp | 322 --------
inst/doc/future-3-topologies.html | 367 ---------
inst/doc/future-3-topologies.md.rsp | 174 ----
inst/vignettes-static/future-1-overview.md.rsp.rsp | 683 ++++++++++++++++
man/eager.Rd | 2 +-
man/lazy.Rd | 2 +-
tests/cluster.R | 4 +-
tests/globals,tricky.R | 9 +
vignettes/future-1-overview.md.rsp | 652 +++++++++++++++
vignettes/future-2-issues.md.rsp | 36 +
44 files changed, 3220 insertions(+), 2381 deletions(-)
diff --git a/.Rbuildignore b/.Rbuildignore
new file mode 100644
index 0000000..968c558
--- /dev/null
+++ b/.Rbuildignore
@@ -0,0 +1,47 @@
+#----------------------------
+# Git and SVN related
+#----------------------------
+^.svn
+^.git
+^.make
+INSTALL[.]md
+OVERVIEW[.]md
+README[.]md
+
+#----------------------------
+# Travis-CI et al.
+#----------------------------
+^[.]travis[.]yml$
+^travis-tool[.]sh$
+^pkg-build[.]sh$
+^appveyor[.]yml$
+^covr-utils.R$
+^[.]covr[.]R$
+^[.]covr[.]rds$
+
+#----------------------------
+# R related
+#----------------------------
+Rplots.pdf$
+^cran-comments[.].*$
+^vignettes/.*[.](pdf|PDF)$
+^vignettes/.*[.](r|R)$
+^vignettes/[.]install_extras$
+^Makefile$
+^incl
+^NAMESPACE,.*[.]txt$
+^nohup.*$
+^[.]R
+^[.]benchmark
+^[.]devel
+^[.]test
+^[.]check
+^.*[.]tar[.]gz$
+
+#----------------------------
+# Package specific
+#----------------------------
+^[.]BatchJobs[.]R$
+[.]future
+
+
diff --git a/.Rinstignore b/.Rinstignore
new file mode 100644
index 0000000..da2aee9
--- /dev/null
+++ b/.Rinstignore
@@ -0,0 +1,5 @@
+# Certain LaTeX files (e.g. bib, bst, sty) must be part of the build
+# such that they are available for R CMD check. These are excluded
+# from the install using .Rinstignore in the top-level directory
+# such as this one.
+doc/.*[.](bib|bst|sty)$
diff --git a/.covr.R b/.covr.R
new file mode 100644
index 0000000..c9fa22a
--- /dev/null
+++ b/.covr.R
@@ -0,0 +1,27 @@
+#################################################################
+# Test coverage
+#
+# * covr-utils: https://github.com/HenrikBengtsson/covr-utils
+# * covr: https://github.com/jimhester/covr
+# * Coveralls: https://coveralls.io/
+#
+# Henrik Bengtsson
+#################################################################
+if (!file_test("-f", "covr-utils.R")) {
+ source("http://callr.org/install#R.utils[u]")
+ R.utils::downloadFile("https://raw.githubusercontent.com/HenrikBengtsson/covr-utils/master/covr-utils.R")
+}
+
+source("covr-utils.R")
+
+# Exclusion rules
+excl <- exclusions(
+ filter(r_files(), covr_lines), # Apply 'covr:' rules in source code
+ filter(r_files(), stop_lines) # Skip lines with stop().
+)
+str(excl)
+
+# Run through tests, record source code coverage, and
+# publish to Coveralls
+covr <- covr_package(exclusions=excl, quiet=FALSE, use_try=FALSE)
+saveRDS(covr, file=".covr.rds")
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..41e9bc6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,16 @@
+.Rhistory
+*~
+**/*~
+.R
+.benchmark
+.check
+.devel
+.test
+*.o
+*.dll
+*.Rout
+.RData
+*.Rproj*
+*.swp
+.covr.rds
+.future
diff --git a/.make/Makefile b/.make/Makefile
new file mode 100644
index 0000000..ce331ea
--- /dev/null
+++ b/.make/Makefile
@@ -0,0 +1,475 @@
+# Makefile for R packages
+
+# CORE MACROS
+ifeq ($(OS), Windows_NT)
+CD=cd
+CURDIR=$(subst \,/,$(shell cmd.exe /C cd))
+FSEP=;
+else
+CD=cd -P "$(CURDIR)"; cd # This handles the case when CURDIR is a softlink
+FSEP=:
+endif
+CP=cp
+MAKE=make
+MV=mv
+RM=rm -f
+MKDIR=mkdir -p
+RMDIR=$(RM) -r
+GIT=git
+
+# PACKAGE MACROS
+PKG_VERSION := $(shell grep -i ^version DESCRIPTION | cut -d : -d \ -f 2)
+PKG_NAME := $(shell grep -i ^package DESCRIPTION | cut -d : -d \ -f 2)
+PKG_DIR := $(shell basename "$(CURDIR)")
+PKG_DIR := $(CURDIR)
+PKG_TARBALL := $(PKG_NAME)_$(PKG_VERSION).tar.gz
+PKG_ZIP := $(PKG_NAME)_$(PKG_VERSION).zip
+PKG_TGZ := $(PKG_NAME)_$(PKG_VERSION).tgz
+
+# FILE MACROS
+FILES_R := $(wildcard R/*.R)
+FILES_DATA := $(wildcard data/*)
+FILES_MAN := $(wildcard man/*.Rd)
+FILES_INCL := $(wildcard incl/*)
+FILES_INST := $(wildcard inst/* inst/*/* inst/*/*/* inst/*/*/*/*)
+FILES_VIGNETTES := $(wildcard vignettes/* vignettes/.install_extras)
+FILES_SRC := $(wildcard src/* src/*/* src/*/*/* src/*/*/*/* src/*/*/*/*/* src/*/*/*/*/*/* src/*/*/*/*/*/*/* src/*/*/*/*/*/*/*/*)
+FILES_SRC_C := $(wildcard src/*.c)
+FILES_SRC_H := $(wildcard src/*.h)
+FILES_TESTS := $(wildcard tests/*.R)
+FILES_NEWS := $(wildcard NEWS inst/NEWS)
+FILES_MISC := $(wildcard README.md)
+FILES_ROOT := DESCRIPTION NAMESPACE $(wildcard .Rbuildignore .Rinstignore)
+PKG_FILES := $(FILES_ROOT) $(FILES_NEWS) $(FILES_R) $(FILES_DATA) $(FILES_MAN) $(FILES_INST) $(FILES_VIGNETTES) $(FILES_SRC) $(FILES_TESTS) $(FILES_MISC)
+FILES_MAKEFILE := $(wildcard ../../Makefile)
+
+# Has vignettes in 'vignettes/' or 'inst/doc/'?
+DIR_VIGNS := $(wildcard vignettes inst/doc)
+
+# R MACROS
+R = R
+R_SCRIPT = Rscript
+R_HOME := $(shell $(R_SCRIPT) -e "cat(R.home())")
+
+## R_USE_CRAN := $(shell $(R_SCRIPT) -e "cat(Sys.getenv('R_USE_CRAN', 'FALSE'))")
+R_NO_INIT := --no-init-file
+R_VERSION_STATUS := $(shell $(R_SCRIPT) -e "status <- tolower(R.version[['status']]); if (regexpr('unstable', status) != -1L) status <- 'devel'; cat(status)")
+R_VERSION_X_Y := $(shell $(R_SCRIPT) -e "cat(gsub('[.][0-9]+$$', '', getRversion()))")
+R_VERSION := $(shell $(R_SCRIPT) -e "cat(as.character(getRversion()))")
+R_VERSION_FULL := $(R_VERSION)$(R_VERSION_STATUS)
+R_LIBS_USER_X := $(shell $(R_SCRIPT) -e "cat(.libPaths()[1])")
+R_INCLUDE := $(shell $(R_SCRIPT) -e "cat(R.home('include'))")
+R_OUTDIR := ../_R-$(R_VERSION_FULL)
+## R_BUILD_OPTS :=
+## R_BUILD_OPTS := $(R_BUILD_OPTS) --no-build-vignettes
+R_CHECK_OUTDIR := $(R_OUTDIR)/$(PKG_NAME).Rcheck
+_R_CHECK_CRAN_INCOMING_ = $(shell $(R_SCRIPT) -e "cat(Sys.getenv('_R_CHECK_CRAN_INCOMING_', 'FALSE'))")
+_R_CHECK_XREFS_REPOSITORIES_ = $(shell if test "$(_R_CHECK_CRAN_INCOMING_)" = "TRUE"; then echo ""; else echo "invalidURL"; fi)
+_R_CHECK_FULL_ = $(shell $(R_SCRIPT) -e "cat(Sys.getenv('_R_CHECK_FULL_', ''))")
+R_CHECK_OPTS = --as-cran --timings $(shell if test "$(_R_CHECK_USE_VALGRIND_)" = "TRUE"; then echo "--use-valgrind"; fi)
+R_RD4PDF = $(shell $(R_SCRIPT) -e "if (getRversion() < 3) cat('times,hyper')")
+R_CRAN_OUTDIR := $(R_OUTDIR)/$(PKG_NAME)_$(PKG_VERSION).CRAN
+
+HAS_ASPELL := $(shell $(R_SCRIPT) -e "cat(Sys.getenv('HAS_ASPELL', !inherits(try(aspell('DESCRIPTION', control=c('--master=en_US', '--add-extra-dicts=en_GB'), dictionaries='en_stats', program='aspell'), silent=TRUE), 'try-error')))")
+
+## Git related
+GIT_BRANCH := $(shell $(GIT) symbolic-ref --short HEAD)
+GIT_BRANCH := $(subst /,-,$(GIT_BRANCH))
+GIT_COMMIT := $(shell $(GIT) log -1 --format="%h")
+R_LIBS_BRANCH := $(CURDIR)/.R/$(GIT_BRANCH)
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Main
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+all: build install check
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Displays macros
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+debug:
+ @echo CURDIR=\'$(CURDIR)\'
+ @echo R_HOME=\'$(R_HOME)\'
+ @echo
+ @echo PKG_DIR=\'$(PKG_DIR)\'
+ @echo PKG_NAME=\'$(PKG_NAME)\'
+ @echo PKG_VERSION=\'$(PKG_VERSION)\'
+ @echo PKG_TARBALL=\'$(PKG_TARBALL)\'
+ @echo
+ @echo HAS_ASPELL=\'$(HAS_ASPELL)\'
+ @echo
+ @echo R=\'$(R)\'
+## @echo R_USE_CRAN=\'$(R_USE_CRAN)\'
+ @echo R_NO_INIT=\'$(R_NO_INIT)\'
+ @echo R_SCRIPT=\'$(R_SCRIPT)\'
+ @echo R_VERSION_X_Y=\'$(R_VERSION_X_Y)\'
+ @echo R_VERSION=\'$(R_VERSION)\'
+ @echo R_VERSION_STATUS=\'$(R_VERSION_STATUS)\'
+ @echo R_VERSION_FULL=\'$(R_VERSION_FULL)\'
+ @echo R_LIBS_USER_X=\'$(R_LIBS_USER_X)\'
+ @echo R_INCLUDE=\'$(R_INCLUDE)\'
+ @echo R_OUTDIR=\'$(R_OUTDIR)\'
+ @echo
+ @echo "Default packages:" $(shell $(R) --slave -e "cat(paste(getOption('defaultPackages'), collapse=', '))")
+ @echo
+ @echo R_BUILD_OPTS=\'$(R_BUILD_OPTS)\'
+ @echo
+ @echo R_CHECK_OUTDIR=\'$(R_CHECK_OUTDIR)\'
+ @echo _R_CHECK_CRAN_INCOMING_=\'$(_R_CHECK_CRAN_INCOMING_)\'
+ @echo _R_CHECK_XREFS_REPOSITORIES_=\'$(_R_CHECK_XREFS_REPOSITORIES_)\'
+ @echo _R_CHECK_FULL_=\'$(_R_CHECK_FULL_)\'
+ @echo R_CHECK_OPTS=\'$(R_CHECK_OPTS)\'
+ @echo R_RD4PDF=\'$(R_RD4PDF)\'
+ @echo
+ @echo R_CRAN_OUTDIR=\'$(R_CRAN_OUTDIR)\'
+ @echo
+
+
+debug_full: debug
+ @echo
+ @echo FILES_ROOT=\'$(FILES_ROOT)\'
+ @echo FILES_R=\'$(FILES_R)\'
+ @echo FILES_DATA=\'$(FILES_DATA)\'
+ @echo FILES_MAN=\'$(FILES_MAN)\'
+ @echo FILES_INST=\'$(FILES_INST)\'
+ @echo FILES_VIGNETTES=\'$(FILES_VIGNETTES)\'
+ @echo FILES_SRC=\'$(FILES_SRC)\'
+ @echo FILES_TESTS=\'$(FILES_TESTS)\'
+ @echo FILES_INCL=\'$(FILES_INCL)\'
+ @echo FILES_MISC=\'$(FILES_MISC)\'
+ @echo
+ @echo DIR_VIGNS=\'$(DIR_VIGNS)\'
+ @echo dirname\(DIR_VIGNS\)=\'$(shell dirname $(DIR_VIGNS))\'
+ @echo
+ @echo GIT_BRANCH=\'$(GIT_BRANCH)\'
+ @echo GIT_COMMIT=\'$(GIT_COMMIT)\'
+ @echo R_LIBS_BRANCH=\'$(R_LIBS_BRANCH)\'
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Update / install
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Update existing packages
+update:
+ $(R_SCRIPT) -e "try(update.packages(ask=FALSE)); source('http://bioconductor.org/biocLite.R'); biocLite(ask=FALSE);"
+
+# Install missing dependencies
+deps: DESCRIPTION
+ $(MAKE) update
+ $(R_SCRIPT) -e "x <- unlist(strsplit(read.dcf('DESCRIPTION',fields=c('Depends', 'Imports', 'Suggests')),',')); x <- gsub('([[:space:]]*|[(].*[)])', '', x); libs <- .libPaths()[file.access(.libPaths(), mode=2) == 0]; x <- unique(setdiff(x, c('R', rownames(installed.packages(lib.loc=libs))))); if (length(x) > 0) { try(install.packages(x)); x <- unique(setdiff(x, c('R', rownames(installed.packages(lib.loc=libs))))); source('http://bioconductor.org/biocLite.R'); biocLite(x); }"
+
+setup: update deps
+ $(R_SCRIPT) -e "source('http://aroma-project.org/hbLite.R'); hbLite('R.oo')"
+
+ns:
+ $(R_SCRIPT) -e "library('$(PKG_NAME)'); source('X:/devtools/NAMESPACE.R'); writeNamespaceSection('$(PKG_NAME)'); writeNamespaceImports('$(PKG_NAME)');"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Build source tarball
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_OUTDIR)/$(PKG_TARBALL): $(PKG_FILES)
+ $(MKDIR) $(R_OUTDIR)
+ $(RM) $@
+ $(CD) $(R_OUTDIR);\
+ $(R) $(R_NO_INIT) CMD build $(R_BUILD_OPTS) $(PKG_DIR)
+
+build: $(R_OUTDIR)/$(PKG_TARBALL)
+
+build_force:
+ $(RM) $(R_OUTDIR)/$(PKG_TARBALL)
+ $(MAKE) install
+
+# Make sure the tarball is readable
+build_fix: $(R_OUTDIR)/$(PKG_TARBALL)
+ifeq ($(OS), Windows_NT)
+ ifeq ($(USERNAME), hb)
+ $(MKDIR) X:/tmp/$(R_VERSION_FULL)
+ $(CP) -f $< X:/tmp/$(R_VERSION_FULL)/
+ $(RM) $<
+ $(MV) X:/tmp/$(R_VERSION_FULL)/$(<F) $<
+ endif
+endif
+
+build_fast: $(PKG_FILES)
+ $(MKDIR) $(R_OUTDIR)
+ $(RM) $@
+ $(CD) $(R_OUTDIR);\
+ $(R) $(R_NO_INIT) CMD build --keep-empty-dirs --no-build-vignettes --no-manual --no-resave-data --compact-vignettes="no" $(R_BUILD_OPTS) $(PKG_DIR)
+
+build: $(R_OUTDIR)/$(PKG_TARBALL)
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Install on current system
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_LIBS_USER_X)/$(PKG_NAME)/DESCRIPTION: $(R_OUTDIR)/$(PKG_TARBALL) build_fix
+ $(CD) $(R_OUTDIR);\
+ $(R) --no-init-file CMD INSTALL $(PKG_TARBALL)
+
+install: $(R_LIBS_USER_X)/$(PKG_NAME)/DESCRIPTION
+
+install_force:
+ $(RM) $(R_LIBS_USER_X)/$(PKG_NAME)/DESCRIPTION
+ $(MAKE) install
+
+install_fast:
+ $(CD) $(R_OUTDIR);\
+ $(R) --no-init-file CMD INSTALL --no-docs --no-multiarch --no-byte-compile --no-test-load $(PKG_TARBALL)
+
+
+$(R_LIBS_BRANCH)/$(PKG_NAME)/DESCRIPTION: $(R_OUTDIR)/$(PKG_TARBALL) build_fix
+ $(CD) $(R_OUTDIR);\
+ $(MKDIR) $(R_LIBS_BRANCH);\
+ $(R) --no-init-file CMD INSTALL --library=$(R_LIBS_BRANCH) $(PKG_TARBALL)
+
+install_branch: $(R_LIBS_BRANCH)/$(PKG_NAME)/DESCRIPTION
+
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Check source tarball
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_CHECK_OUTDIR)/.check.complete: $(R_OUTDIR)/$(PKG_TARBALL) build_fix
+ $(CD) $(R_OUTDIR);\
+ $(RM) -r $(PKG_NAME).Rcheck;\
+ export _R_CHECK_CRAN_INCOMING_=$(_R_CHECK_CRAN_INCOMING_);\
+ export _R_CHECK_CRAN_INCOMING_USE_ASPELL_=$(HAS_ASPELL);\
+ export _R_CHECK_XREFS_REPOSITORIES_=$(_R_CHECK_XREFS_REPOSITORIES_);\
+ export _R_CHECK_DOT_INTERNAL_=1;\
+ export _R_CHECK_USE_CODETOOLS_=1;\
+ export _R_CHECK_FORCE_SUGGESTS_=0;\
+ export R_RD4PDF=$(R_RD4PDF);\
+ export _R_CHECK_FULL_=$(_R_CHECK_FULL_);\
+ $(R) --no-init-file CMD check $(R_CHECK_OPTS) $(PKG_TARBALL);\
+ echo done > $(PKG_NAME).Rcheck/.check.complete
+
+check: $(R_CHECK_OUTDIR)/.check.complete
+
+check_force:
+ $(RM) -r $(R_CHECK_OUTDIR)
+ $(MAKE) check
+
+clang:
+ clang -c -pedantic -Wall -I$(R_INCLUDE) src/*.c
+ $(RM) *.o
+
+clang-ubsan:
+ clang -fsanitize=undefined -I$(R_INCLUDE) -c src/*.c
+ $(RM) *.o
+
+valgrind_scan:
+ grep -E "^==.*==[ ]+(at|by) 0x" $(R_CHECK_OUTDIR)/tests*/*.Rout | cat
+ grep "^==.* ERROR SUMMARY:" $(R_CHECK_OUTDIR)/tests*/*.Rout | grep -v -F "ERROR SUMMARY: 0 errors" | cat
+
+valgrind:
+ export _R_CHECK_USE_VALGRIND_=TRUE;\
+ $(MAKE) check_force
+ $(MAKE) valgrind_scan
+
+# Check the line width of incl/*.(R|Rex) files [max 100 chars in R devel]
+check_Rex:
+ $(R_SCRIPT) -e "if (!file.exists('incl')) quit(status=0); setwd('incl/'); fs <- dir(pattern='[.](R|Rex)$$'); ns <- sapply(fs, function(f) max(nchar(readLines(f)))); ns <- ns[ns > 100]; print(ns); if (length(ns) > 0L) quit(status=1)"
+
+
+covr:
+ $(R_SCRIPT) -e "source('.covr.R'); covr::shine(covr)"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Install and build binaries
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_OUTDIR)/$(PKG_ZIP): $(R_OUTDIR)/$(PKG_TARBALL) build_fix
+ $(CD) $(R_OUTDIR);\
+ $(R) --no-init-file CMD INSTALL --build --merge-multiarch $(PKG_TARBALL)
+
+binary: $(R_OUTDIR)/$(PKG_ZIP)
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Build Rd help files from Rdoc comments
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+rox:
+ $(R_SCRIPT) -e "roxygen2::roxygenize()"
+
+Rd: check_Rex
+ $(R_SCRIPT) -e "setwd('..'); Sys.setlocale(locale='C'); R.oo::compileRdoc('$(PKG_NAME)', path='$(PKG_DIR)')"
+
+%.Rd:
+ $(R_SCRIPT) -e "setwd('..'); Sys.setlocale(locale='C'); R.oo::compileRdoc('$(PKG_NAME)', path='$(PKG_DIR)', '$*.R')"
+
+missing_Rd:
+ $(R_SCRIPT) -e "x <- readLines('$(R_CHECK_OUTDIR)/00check.log'); from <- grep('Undocumented code objects:', x)+1; if (length(from) > 0L) { to <- grep('All user-level objects', x)-1; x <- x[from:to]; x <- gsub('^[ ]*', '', x); x <- gsub('[\']', '', x); cat(x, sep='\n', file='999.missingdocs.txt'); }"
+
+spell_Rd:
+ $(R_SCRIPT) -e "f <- list.files('man', pattern='[.]Rd$$', full.names=TRUE); utils::aspell(f, filter='Rd')"
+
+
+spell_NEWS:
+ $(R_SCRIPT) -e "utils::aspell('$(FILES_NEWS)')"
+
+spell:
+ $(R_SCRIPT) -e "utils::aspell('DESCRIPTION', filter='dcf')"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Build package vignettes
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_OUTDIR)/vigns: install
+ $(MKDIR) $(R_OUTDIR)/vigns/$(shell dirname $(DIR_VIGNS))
+ $(CP) DESCRIPTION $(R_OUTDIR)/vigns/
+ $(CP) -r $(DIR_VIGNS) $(R_OUTDIR)/vigns/$(shell dirname $(DIR_VIGNS))
+ $(CD) $(R_OUTDIR)/vigns;\
+ $(R_SCRIPT) -e "v <- tools::buildVignettes(dir='.'); file.path(getwd(), v[['outputs']])"
+
+vignettes: $(R_OUTDIR)/vigns
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Run package tests
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_OUTDIR)/tests/%.R: $(FILES_TESTS)
+ $(RMDIR) $(R_OUTDIR)/tests
+ $(MKDIR) $(R_OUTDIR)/tests
+ $(CP) $? $(R_OUTDIR)/tests
+
+test_files: $(R_OUTDIR)/tests/*.R
+
+test: $(R_OUTDIR)/tests/%.R
+ $(CD) $(R_OUTDIR)/tests;\
+ $(R_SCRIPT) -e "for (f in list.files(pattern='[.]R$$')) { print(f); source(f, echo=TRUE) }"
+
+test_full: $(R_OUTDIR)/tests/%.R
+ $(CD) $(R_OUTDIR)/tests;\
+ export _R_CHECK_FULL_=TRUE;\
+ $(R_SCRIPT) -e "for (f in list.files(pattern='[.]R$$')) { print(f); source(f, echo=TRUE) }"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Benchmarking
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+R_branch:
+ R_LIBS="$(R_LIBS_USER_X)$(FSEP)$(R_LIBS)" R_LIBS_USER="$(R_LIBS_BRANCH)" $(R)
+
+benchmark:
+ $(MKDIR) .benchmark/$(PKG_VERSION);\
+ $(CD) .benchmark/$(PKG_VERSION);\
+ $(R_SCRIPT) -e "$(PKG_NAME):::benchmark('index')"
+
+benchmark_branch:
+ $(MKDIR) .benchmark/$(PKG_VERSION)_$(GIT_BRANCH)_$(GIT_COMMIT);\
+ $(CD) .benchmark/$(PKG_VERSION)_$(GIT_BRANCH)_$(GIT_COMMIT);\
+ R_LIBS="$(R_LIBS_USER_X)$(FSEP)$(R_LIBS)" R_LIBS_USER="$(R_LIBS_BRANCH)" $(R_SCRIPT) -e "$(PKG_NAME):::benchmark('index')"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Miscellaneous development tools
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+## Fully expanded src/*.c files
+.devel/src/%: src/% $(FILES_SRC)
+ $(MKDIR) .devel/src/;\
+ gcc -I$(R_INCLUDE) -E $< | sed -e '/./b' -e :n -e 'N;s/\n$$//;tn' > .devel/$<
+
+.devel/src/all: $(FILES_SRC)
+ for f in $(FILES_SRC_C); do\
+ echo $$f;\
+ $(MAKE) .devel/$$f;\
+ done
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Run extensive CRAN submission checks
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+$(R_CRAN_OUTDIR)/$(PKG_TARBALL): $(R_OUTDIR)/$(PKG_TARBALL) build_fix
+ $(MKDIR) $(R_CRAN_OUTDIR)
+ $(CP) $(R_OUTDIR)/$(PKG_TARBALL) $(R_CRAN_OUTDIR)
+
+$(R_CRAN_OUTDIR)/$(PKG_NAME),EmailToCRAN.txt: $(R_CRAN_OUTDIR)/$(PKG_TARBALL)
+ $(CD) $(R_CRAN_OUTDIR);\
+ $(R_SCRIPT) -e "RCmdCheckTools::testPkgsToSubmit(delta=2/3)"
+
+cran_setup: $(R_CRAN_OUTDIR)/$(PKG_TARBALL)
+ $(R_SCRIPT) -e "if (!nzchar(system.file(package='RCmdCheckTools'))) { source('http://aroma-project.org/hbLite.R'); hbLite('RCmdCheckTools', devel=TRUE); }"
+
+cran: cran_setup $(R_CRAN_OUTDIR)/$(PKG_NAME),EmailToCRAN.txt
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Send to win-builder server
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+WIN_BUILDER = win-builder.r-project.org
+win-builder-devel: $(R_OUTDIR)/$(PKG_TARBALL)
+ curl -v -T $? ftp://anonymous@$(WIN_BUILDER)/R-devel/
+
+win-builder-release: $(R_OUTDIR)/$(PKG_TARBALL)
+ curl -v -T $? ftp://anonymous@$(WIN_BUILDER)/R-release/
+
+win-builder: win-builder-devel win-builder-release
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Local repositories
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+ifeq ($(OS), Windows_NT)
+REPOS_PATH = T:/My\ Repositories/braju.com/R
+else
+REPOS_PATH = /tmp/hb/repositories/braju.com/R
+endif
+REPOS_SRC := $(REPOS_PATH)/src/contrib
+
+$(REPOS_SRC):
+ $(MKDIR) "$@"
+
+$(REPOS_SRC)/$(PKG_TARBALL): $(R_OUTDIR)/$(PKG_TARBALL) $(REPOS_SRC)
+ $(CP) $(R_OUTDIR)/$(PKG_TARBALL) $(REPOS_SRC)
+
+repos: $(REPOS_SRC)/$(PKG_TARBALL)
+
+Makefile: $(FILES_MAKEFILE)
+ $(R_SCRIPT) -e "d <- 'Makefile'; s <- '../../Makefile'; if (file_test('-nt', s, d) && (regexpr('Makefile for R packages', readLines(s, n=1L)) != -1L)) file.copy(s, d, overwrite=TRUE)"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# Refresh
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.make/Makefile:
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/r-package-files/master/.make/Makefile', path='.make/')"
+
+.make/.travis.yml.rsp:
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/r-package-files/master/.make/.travis.yml.rsp', path='.make/')"
+
+.make/appveyor.yml.rsp:
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/r-package-files/master/.make/appveyor.yml.rsp', path='.make/')"
+
+.make/README.md.rsp:
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/r-package-files/master/.make/README.md.rsp', path='.make/')"
+
+.covr.R:
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/covr-utils/master/.covr.R')"
+
+clean:
+ $(RM) .make/.travis.yml.rsp .make/appveyor.yml.rsp .make/README.md.rsp .covr.R
+ $(RM) covr-utils.R
+
+refresh: clean
+ $(MAKE) --silent .make/.travis.yml.rsp
+ $(MAKE) --silent .make/appveyor.yml.rsp
+ $(MAKE) --silent .make/README.md.rsp
+ $(MAKE) --silent .covr.R
+ $(R_SCRIPT) -e "R.utils::downloadFile('https://raw.githubusercontent.com/HenrikBengtsson/r-package-files/master/.make/Makefile', path='.make/', skip=FALSE)"
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# GitHub, Travis CI, ...
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+README.md: .make/README.md.rsp
+ $(R_SCRIPT) -e "R.rsp::rfile('$<', postprocess=FALSE)"
+
+.travis.yml: .make/.travis.yml.rsp
+ $(R_SCRIPT) -e "R.rsp::rfile('$<', postprocess=FALSE)"
+
+appveyor.yml: .make/appveyor.yml.rsp
+ $(R_SCRIPT) -e "R.rsp::rfile('$<', postprocess=FALSE)"
+
+config: .travis.yml appveyor.yml README.md
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 0000000..b022f0c
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,38 @@
+#----------------------------------------------------------------
+# Travis-CI configuration for R packages
+#
+# REFERENCES:
+# * Travis CI: https://docs.travis-ci.com/user/languages/r
+# * covr: https://github.com/jimhester/covr
+#
+# Validate your .travis.yml file at http://lint.travis-ci.org/
+#----------------------------------------------------------------
+language: r
+sudo: false
+cache: packages
+
+os:
+ - linux
+ - osx
+
+r:
+ - oldrel
+ - release
+ - devel
+
+matrix:
+ exclude:
+ - os: osx
+ r: devel
+
+r_github_packages:
+ - jimhester/covr
+
+after_success:
+ - Rscript -e 'covr::codecov(quiet=FALSE)'
+
+notifications:
+ email:
+ on_success: change
+ on_failure: change
+
diff --git a/DESCRIPTION b/DESCRIPTION
index 4a86308..7e4d793 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,9 +1,15 @@
Package: future
-Version: 1.0.0
+Version: 1.0.1
Title: A Future API for R
-Imports: digest, globals (>= 0.6.1), listenv (>= 0.6.0), parallel,
- utils
-Suggests: R.rsp, markdown
+Imports:
+ digest,
+ globals (>= 0.6.1),
+ listenv (>= 0.6.0),
+ parallel,
+ utils
+Suggests:
+ R.rsp,
+ markdown
VignetteBuilder: R.rsp
Authors at R: c(person("Henrik", "Bengtsson", role=c("aut", "cre", "cph"),
email = "henrikb at braju.com"))
@@ -34,9 +40,3 @@ LazyLoad: TRUE
URL: https://github.com/HenrikBengtsson/future
BugReports: https://github.com/HenrikBengtsson/future/issues
RoxygenNote: 5.0.1
-NeedsCompilation: no
-Packaged: 2016-06-24 06:16:46 UTC; hb
-Author: Henrik Bengtsson [aut, cre, cph]
-Maintainer: Henrik Bengtsson <henrikb at braju.com>
-Repository: CRAN
-Date/Publication: 2016-06-24 09:53:40
diff --git a/MD5 b/MD5
deleted file mode 100644
index bcf0bfe..0000000
--- a/MD5
+++ /dev/null
@@ -1,150 +0,0 @@
-d9e40c76d17986a9c3836805379d874a *DESCRIPTION
-9aaad22d12c436f593215a7446671494 *NAMESPACE
-87c2792323a8f4b24db7bdb69ef6c5d1 *NEWS
-b1e620832f566c83548301d9a6037e3a *R/ClusterFuture-class.R
-f8920b0c54839f391327447172ab6f1d *R/ClusterRegistry.R
-eb7a1d5e5aee29917cd77ab8268911d5 *R/ConstantFuture-class.R
-f621e87dbd5a2963d9b705c7508375bb *R/EagerFuture-class.R
-20f590e4fadca84f2c82d80b6af83f8d *R/Future-class.R
-f4c5670246362c9d233b49e02cefcd8c *R/FutureError-class.R
-f49371755687bb8745bde010f324cde4 *R/FutureRegistry.R
-82d6c3bcf971b00f82918b735217dcdb *R/LazyFuture-class.R
-1239870f0037948407f8f4752efea47d *R/MulticoreFuture-class.R
-4640bc2ba4bd2b94a715b3e9fdd87a0b *R/MultiprocessFuture-class.R
-8e922100c5b70e732c657dfbd50f718b *R/MultisessionFuture-class.R
-cc827eb023a4619ee8813220131b184c *R/UniprocessFuture-class.R
-3fa59f74a7528ed471031225f0abb4b1 *R/availableCores.R
-83e64b9f6e8361620fbea1a6e6377fd9 *R/backtrace.R
-166fc03f07c693854f2f0f6fae0b9414 *R/cluster.R
-adba25fecf647a953f794bd82edfdef2 *R/constant.R
-2dab326b95199f114d8779d59db4b97e *R/eager.R
-b913c5a87fc900714ce598a801904f4f *R/flapply.R
-26aab9bfdae0533bb4643da3779f6021 *R/future.R
-eb912abdea8a4687765ab065483e7067 *R/futureAssign.R
-afe2d79f9142d440aa75121f4cd30767 *R/futureAssign_OP.R
-e652fb677a0fb8c941f07fb8abdb219a *R/futureCall.R
-ee72a50a50b8dfb3ff5fc68cbc8a2245 *R/futureOf.R
-6ddca8968f151063e6797d464ce06722 *R/futures.R
-82fc04c9c34e35ce7c030f6a2e187011 *R/globals.R
-cbf0c52e538bfa95032b8e5283c26078 *R/lazy.R
-58898f5ba92ced1528f31e1db588dbe4 *R/mandelbrot.R
-355e9b89fff62d0cb4ea98d38cc366d6 *R/multicore.R
-00762b0836395a64510237d10bba9954 *R/multiprocess.R
-0e5dc1a8b8109c543ed6764627ca37d4 *R/multisession.R
-09c7e46004ed15f1440c6292322bc60f *R/nbrOfWorkers.R
-960857a106a23b81aab37afdadc14daf *R/options.R
-bc8f221d76bf33c012917333f6fa378c *R/plan.R
-beaf9318ec079559d9c0317c948d171f *R/plan_OP.R
-e695c2a384c9d4640ae3de9bb60dc35c *R/remote.R
-c001e66c0bb0e01b58aa5ccde4dc4a3a *R/resolve.R
-c252cf985ed0c07a3466b1a052534bd6 *R/resolved.R
-341328f9a53c1b529fecb5b34fb4d311 *R/signalEarly.R
-af287c41d84cea82cb1c50506eec5946 *R/tweak.R
-2d209b376b3f82d1f40e90d59a0a9ee6 *R/tweakExpression.R
-1e991bb1d9d9b4da9ed2aa804ada2266 *R/tweak_OP.R
-be19af2eaef024cde2e20b0b5445dd27 *R/utils.R
-e3f4b639a8943fc5c2a2391698df288b *R/values.R
-03874e74c87ddd7a7d4741bb3a411e51 *R/whichIndex.R
-374b97fc18d8ae22e8bb7ab98e8bc664 *R/zzz.R
-ee596936fc45e84d8878cdf6a62ed5e0 *build/vignette.rds
-f615957051c16ab204dab55cf45ec170 *demo/00Index
-d6f69bf0e10c4518df2a9b8b763f66df *demo/fibonacci.R
-a82f2b900b5bdcb20f748c8e2ee9080c *demo/mandelbrot.R
-c783b7227c73fa56028acc6f2f778f80 *inst/doc/future-1-overview.html
-db2774171992c81c9304e585c8d1c3c3 *inst/doc/future-2-issues.html
-5dfc3d022e929e7329c9a758611be00d *inst/doc/future-2-issues.md.rsp
-f66e84c4e10109cca314b9c18cd5920f *inst/doc/future-3-topologies.html
-fc40bba23693cd6d2fad08ffec4bbd59 *inst/doc/future-3-topologies.md.rsp
-d15bee49d2cd9d3c1f2725015a53d7de *inst/vignettes-static/incl/future-1-overview-example2.R
-8bb96c0fa173c00903c0ac2d60b9ecf0 *inst/vignettes-static/incl/future-1-overview-example3.R
-07449dd46b66bef5c07af55261c0f951 *man/ClusterFuture-class.Rd
-be030b72200a4ce93c445904824227ed *man/ConstantFuture-class.Rd
-bdf7f66073dfd6cafcd8d6ada4828fef *man/EagerFuture-class.Rd
-ecf508d4599a169a4be0dbe1043f008c *man/Future-class.Rd
-40336f654bed5785399ac1ee9bd68490 *man/FutureError.Rd
-6925f9764dc51e2fd334c6d76e69558f *man/LazyFuture-class.Rd
-895b649d28573d2a9688d0a8cac1443f *man/MulticoreFuture-class.Rd
-0a0dedf22c1dde0532996727d4eee93a *man/MultiprocessFuture-class.Rd
-66c177978f5cb667434b142e7cd2f578 *man/UniprocessFuture-class.Rd
-5c3f42a10800c70cd8c431d673880f6f *man/availableCores.Rd
-cb2eda9d31a1ca1205e06b710f22fa10 *man/backtrace.Rd
-cd4210ebdbe4b2514bd1dff09490e01f *man/cluster.Rd
-9e8bb991f399fae557e86cdaac2b9817 *man/eager.Rd
-61d11dce702377d1209e34d739be62b6 *man/future.Rd
-2276b91a3ded25763867d78bd586462b *man/future.options.Rd
-e283989bbc01b29fabc73de1200a386e *man/futureAssign.Rd
-3f62c268c306b9e62d4bdb6ee878c9a5 *man/futureOf.Rd
-dc6e43957a22e51eb75414a05a763471 *man/futures.Rd
-bb8e6a67ce3bb99456d0e29b9f4e3985 *man/getExpression.Rd
-e529465059c930c23a2aaab0b370130d *man/grapes-plan-grapes.Rd
-8b94fd9bca4f6d580c623617156388a4 *man/grapes-tweak-grapes.Rd
-fad1eebc76d223ca1a93211bdd2227ce *man/lazy.Rd
-903e8d9c18095f373fa01fce5982296f *man/mandelbrot.Rd
-5505777ea63f279c044c89665f0a6790 *man/multicore.Rd
-d8411f4132ef9a6dd2c4a950fb35ec71 *man/multiprocess.Rd
-5f871fca190eca93f6715f496001738a *man/multisession.Rd
-dccf63069814d5f5d9c88126a1a0c4df *man/nbrOfWorkers.Rd
-e8839e33656f8f151e072bcc6aa074d0 *man/plan.Rd
-bc62470c801c6e0da100a6bcd6f9edaf *man/remote.Rd
-2aaeaddd39794557ad09db552050cc5d *man/requestCore.Rd
-87618eab3429cc479870f7bc842d7e6e *man/resolve.Rd
-215eb769db07713345a571baa6c446b4 *man/resolved.Rd
-e8ecc874982305dc716daa4924c1e72a *man/supportsMulticore.Rd
-0557933001b84a991f7fc1aeabddfcc6 *man/tweak.Rd
-f3a5534c5f7d15e3afdf731874539123 *man/usedCores.Rd
-2ddab805cf905e33c6b477946892208c *man/value.Rd
-a790a5d25c60ba4deeb942596c106399 *man/values.Rd
-21c8e4279c5d3ba6b7f2d74f8f878841 *tests/ClusterRegistry.R
-87185f19d8f8a579c1baa8036c89cd34 *tests/Future-class.R
-46e93ef56ccae2810c50676d6ce61806 *tests/FutureError.R
-7d447970b8fab444805b7f72089999a7 *tests/FutureRegistry.R
-0690c893bcbe7da045f804d41e2976d3 *tests/availableCores.R
-303eca91c90c6920bb0eafd95b691555 *tests/backtrace.R
-8dc90618c5c9e389ad4334a9c210a34b *tests/cluster.R
-a790d6ca23e3fa2dce57372a57c3aa90 *tests/constant.R
-de4a479ed6d1df3a99b38a3f94f3b905 *tests/demo.R
-76989f5f9885e7e7d765303e0657c682 *tests/deprecated.R
-e78ccd5326a90a4fa970c8aa9300128c *tests/dotdotdot.R
-afb76583eb69761924b73716ec8aa084 *tests/eager.R
-b9916ed7b205ade7ce49fb25c7eed477 *tests/early-signaling.R
-93f20e9ec979de1b5f3296035ba63414 *tests/flapply.R
-b56c4d40f7aee9a6ecd9062a199c1454 *tests/future.R
-e624a72b72aaf21840cbdc2ca9566c49 *tests/futureAssign.R
-277c3a9b6d20194991ca02ba7b707e36 *tests/futureAssign_OP.R
-35decab113a7224324ac417f18c6caa3 *tests/futureAssign_OP_with_environment.R
-3a419a0225b64f87f63f60694bc8e345 *tests/futureAssign_OP_with_listenv.R
-7cab3efba3107757628619af161d1a80 *tests/futureCall.R
-3286e4bbf59247ef5d55429271941471 *tests/futureOf.R
-d4085449d7bce6cd1f8a0a150ec3396e *tests/futureOf_with_environment.R
-a17a3e037541a7684208af54799466b2 *tests/futureOf_with_listenv.R
-08e069b25d66347a1bce14d2523d2b67 *tests/futures.R
-78988256e19dcb84233417c4f738375c *tests/globals,NSE.R
-8483856603b3577b011a10dc93251ee6 *tests/globals,resolve.R
-99f71f8f9495a67bf42c3e96e08c6421 *tests/globals,toolarge.R
-1a611ea3faa2a6d4659f36a87af0d555 *tests/globals,tricky.R
-713910223d21a743141a1a0f17d8b013 *tests/globalsOf,tweaks.R
-94920fda0b3bdce0bd00e47e4f479ba5 *tests/incl/end.R
-92e237a767aa5339b945fbb2447b7d12 *tests/incl/start,load-only.R
-3fe5b5d1e7981baf93db9ed2fca8ff2c *tests/incl/start.R
-6e367513d56927f61bdcdc7be385d4ae *tests/invalid-owner.R
-12fb3c6f456b5fca7d7a25d5361621e5 *tests/lazy.R
-ca4e6eac9c74f5ecd0d359100a648ac9 *tests/mandelbrot.R
-74954f2f8bc0201f0feb3f0f303f937a *tests/multicore.R
-20eaee89e2f3b68a8857cd913ddfa4ff *tests/multiprocess.R
-5346fc337fac28eb244b4b359fb74e65 *tests/multisession.R
-f5fa85bf0f0bbe156e973248c5f0c84f *tests/nbrOfWorkers.R
-4749a2c46be45bca5fe2ffa3520682e8 *tests/nested_futures,mc.cores.R
-129a66a6c577584caaf02ca68c1b1d5d *tests/plan.R
-9bfaa25aab33db0330dbe14a6a020328 *tests/remote.R
-e0c9f74a417243e21eabb53f88869cb1 *tests/requestCore.R
-a2fc86b56f77cfc5e401a950b26c5e2e *tests/requestNode.R
-3063292ece2925c5d0249ec938458e23 *tests/resolve.R
-3ff72931949acc03502ed8c3cdde8d6a *tests/rng.R
-dfc7a0d6fd758a74fd2131a93b971357 *tests/startup.R
-aa582dc79e84931929053108ada332a9 *tests/transparent.R
-9f11cb052749aae6ef6306621a80449b *tests/tweak.R
-1424be3086f8e2e09479adf3034e437c *tests/utils.R
-d2c40d881613acc74d63de7bccbefeed *tests/uuid.R
-62d15a52d377ebea7e641406ed990ec9 *tests/whichIndex.R
-5dfc3d022e929e7329c9a758611be00d *vignettes/future-2-issues.md.rsp
-fc40bba23693cd6d2fad08ffec4bbd59 *vignettes/future-3-topologies.md.rsp
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..bfaeda6
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,9 @@
+include .make/Makefile
+
+vignettes/future-1-overview.md.rsp: inst/vignettes-static/future-1-overview.md.rsp.rsp
+ $(CD) $(@D); \
+ $(R_SCRIPT) -e "R.rsp::rfile" ../$< --postprocess=FALSE
+ $(RM) README.md
+ $(MAKE) README.md
+
+vigs: vignettes/future-1-overview.md.rsp
diff --git a/NEWS b/NEWS
index f3d2a7a..8062425 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,22 @@
Package: future
===============
+Version: 1.0.1 [2016-07-04]
+o DOCUMENTATION: Adding section to vignette on globals in formulas
+ describing how they are currently not automatically detected
+ and how to explicitly export them.
+o ROBUSTNESS: For the special case where 'remote' futures use
+ workers = "localhost" they now uses the exact same R executable
+ as the main / calling R session (in all other cases it uses
+ whatever 'Rscript' is found in the PATH).
+o FutureError now extends simpleError and no longer the error
+ class of captured errors.
+o BUG FIX: Since future 0.13.0, a global 'pkg' would be
+ overwritten by the name of the last package attached in future.
+o BUG FIX: Futures that generated R.oo::Exception errors, they
+ triggered another internal error.
+
+
Version: 1.0.0 [2016-06-24]
o GLOBALS: Falsely identified global variables no longer generate
an error when the future is created. Instead, we leave it to R
diff --git a/OVERVIEW.md b/OVERVIEW.md
new file mode 100644
index 0000000..784f03a
--- /dev/null
+++ b/OVERVIEW.md
@@ -0,0 +1,14 @@
+<%
+## Reuse the future vignette
+md <- R.rsp::rstring(file="vignettes/future-1-overview.md.rsp", postprocess=FALSE)
+
+## Drop the header
+md <- unlist(strsplit(md, split="\n", fixed=TRUE))
+md <- md[-seq_len(grep("^## ", md)[1]-1)]
+
+## Drop the footer
+md <- md[seq_len(grep("^---", md)[1]-1)]
+
+## Output
+cat(md, sep="\n")
+%>
diff --git a/R/Future-class.R b/R/Future-class.R
index b520656..f67d172 100644
--- a/R/Future-class.R
+++ b/R/Future-class.R
@@ -156,8 +156,9 @@ value.Future <- function(future, signal=TRUE, ...) {
value <- future$value
if (signal && future$state == 'failed') {
- mdebug("Future state: %s", sQuote(value))
- stop(FutureError(value, future=future))
+ mdebug("Future state: %s", sQuote(future$state))
+ mdebug("Future value: %s", sQuote(value))
+ stop(FutureError(future))
}
value
@@ -277,17 +278,19 @@ getExpression.Future <- function(future, mc.cores=NULL, ...) {
## informative error message. Because of this, we load the
## namespace first (to get a better error message) and then
## calls library(), which attaches the package. /HB 2016-06-16
- for (pkg in .(pkgs)) {
- loadNamespace(pkg)
- library(pkg, character.only=TRUE)
- }
- oplans <- future::plan("list")
+ ## NOTE: We use local() here such that 'pkg' is not assigned
+ ## to the future environment. /HB 2016-07-03
+ local({
+ for (pkg in .(pkgs)) {
+ loadNamespace(pkg)
+ library(pkg, character.only=TRUE)
+ }
+ })
})
} else {
enter <- bquote({
## covr: skip=2
.(enter)
- oplans <- future::plan("list")
})
}
diff --git a/R/FutureError-class.R b/R/FutureError-class.R
index 6d3e856..36c9f37 100644
--- a/R/FutureError-class.R
+++ b/R/FutureError-class.R
@@ -11,15 +11,29 @@
#' @export
#' @keywords internal
FutureError <- function(message, call=NULL, future=NULL, output=NULL) {
- if (inherits(message, "error")) {
- ex <- message
- } else {
- ex <- simpleError(message, call=call)
+ ## Support different types of input
+ ## NOTE: We could turn this into an S3 method. /HB 2016-07-01
+ if (inherits(message, "Future")) {
+ future <- message
+ value <- future$value
+ stopifnot(inherits(value, "condition"), inherits(value, "error"))
+ cond <- value
+ message <- conditionMessage(cond)
+ } else if (inherits(message, "condition")) {
+ cond <- message
+ message <- conditionMessage(cond)
}
- ex$future <- future
- ex$output <- output
- class(ex) <- unique(c("FutureError", class(ex)))
- ex
+
+ ## Create a basic error object
+ cond <- simpleError(message, call=call)
+
+ ## Record Future object and optional output messages
+ attr(cond, "future") <- future
+ attr(cond, "output") <- output
+
+ class(cond) <- unique(c("FutureError", class(cond)))
+
+ cond
}
@@ -27,8 +41,8 @@ FutureError <- function(message, call=NULL, future=NULL, output=NULL) {
print.FutureError <- function(x, ...) {
NextMethod("print")
- future <- x$future
- output <- x$output
+ future <- attr(x, "future")
+ output <- attr(x, "output")
if (!is.null(future) || !is.null(output)) {
cat("\n\nDEBUG: BEGIN TROUBLESHOOING HELP\n")
@@ -63,7 +77,7 @@ print.FutureError <- function(x, ...) {
#' @export
getOutput.FutureError <- function(x, collapse=NULL, head=NULL, tail=NULL, ...) {
- output <- x$output
+ output <- attr(x, "output")
## Return "as is"?
if (is.null(collapse) && is.null(head) && is.null(tail)) return(output)
diff --git a/R/remote.R b/R/remote.R
index 71c559e..b0c7452 100644
--- a/R/remote.R
+++ b/R/remote.R
@@ -34,12 +34,23 @@ remote <- function(expr, envir=parent.frame(), substitute=TRUE, persistent=TRUE,
stopifnot(length(workers) >= 1L, is.character(workers), !anyNA(workers))
if (is.character(workers)) {
+ homogeneous <- FALSE ## Calls plain 'Rscript'
+
## Guess what type of IP to use
if (is.null(myip)) {
if (all(workers %in% c("localhost", "127.0.0.1"))) {
## For conveniency, if all workers are on the localhost,
- ## then we know that localhost should be used
+ ## then we know that only the local machine will be used.
+
+ ## (a) We use 127.0.0.1 because it's slightly more generic
+ ## than localhost.
myip <- "127.0.0.1"
+
+ ## (b) We can also use the pathname of the currently running
+ ## R session, file.path(R.home("bin"), "Rscript"), rather
+ ## than 'Rscript' which is the best guess we can make for
+ ## a remote machine. This is controlled by 'homogeneous'.
+ homogeneous <- TRUE
} else {
myip <- "<external>"
}
@@ -52,7 +63,7 @@ remote <- function(expr, envir=parent.frame(), substitute=TRUE, persistent=TRUE,
myip <- myInternalIP()
}
- workers <- ClusterRegistry("start", workers=workers, master=myip, homogeneous=FALSE)
+ workers <- ClusterRegistry("start", workers=workers, master=myip, homogeneous=homogeneous)
} else if (!inherits(workers, "cluster")) {
stop("Argument 'workers' is not of class 'cluster': ", class(workers)[1])
}
diff --git a/R/signalEarly.R b/R/signalEarly.R
index d13aa18..0ed329b 100644
--- a/R/signalEarly.R
+++ b/R/signalEarly.R
@@ -18,7 +18,7 @@ signalEarly <- function(future, collect=TRUE, ...) {
value <- future$value
}
- mdebug("signalEarly(): class(v) = c(%s)", paste(class(value), collapse=", "))
+ mdebug("signalEarly(): class(v) = c(%s)", paste(sQuote(class(value)), collapse=", "))
mdebug("signalEarly(): Retrieving value ... DONE")
## Was a condition caught?
@@ -28,7 +28,7 @@ signalEarly <- function(future, collect=TRUE, ...) {
## Signal detected condition
if (inherits(value, "error")) {
- stop(FutureError(value, future=future))
+ stop(FutureError(future))
} else if (inherits(value, "warning")) {
warning(value)
} else if (inherits(value, "message")) {
diff --git a/R/zzz.R b/R/zzz.R
index 2183499..57c0914 100644
--- a/R/zzz.R
+++ b/R/zzz.R
@@ -81,12 +81,12 @@
pathnames <- pathnames[file_test("-f", pathnames)]
if (length(pathnames) == 0) {
- mdebug("Future scripts identified: <none>")
+ mdebug("Future startup scripts identified: <none>")
return()
}
- mdebug("Future scripts identified: %s", paste(sQuote(pathnames), collapse=", "))
+ mdebug("Future startup scripts identified: %s", paste(sQuote(pathnames), collapse=", "))
pathname <- pathnames[1]
- mdebug("Future script to load: %s", sQuote(pathname))
+ mdebug("Future startup script to load: %s", sQuote(pathname))
tryCatch({
source(pathname, chdir=FALSE, echo=FALSE, local=FALSE)
}, error = function(ex) {
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1909de3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,655 @@
+# future: A Future API for R
+
+## Introduction
+The purpose of the [future] package is to provide a very simple and uniform way of evaluating R expressions asynchronously using various resources available to the user.
+
+In programming, a _future_ is an abstraction for a _value_ that may be available at some point in the future. The state of a future can either be _unresolved_ or _resolved_. As soon as it is resolved, the value is available instantaneously. If the value is queried while the future is still unresolved, the current process is _blocked_ until the future is resolved. It is possible to check whether a future is resolved or not without blocking. Exactly how and when futures are resolved d [...]
+
+Here is an example illustrating how the basics of futures work. First, consider the following code snippet that uses plain R code:
+```r
+> v <- {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+It works by assigning the value of an expression to variable `v` and we then print the value of `v`. Moreover, when the expression for `v` is evaluated we also print a message.
+
+Here is the same code snippet modified to use futures instead:
+```r
+> library("future")
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+The difference is in how `v` is constructed; with plain R we use `<-` whereas with futures we use `%<-%`.
+
+So why are futures useful? Because we can choose to evaluate the future expression in a separate R process asynchronously by simply switching settings as:
+```r
+> library("future")
+> plan(multiprocess)
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+> v
+[1] 3.14
+```
+With asynchronous futures, the current/main R process does _not_ block, which means it is available for further processing while the futures are being resolved
+in separates processes running in the background. In other words, futures provide a simple but yet powerful construct for parallel and / or distributed processing in R.
+
+
+Now, if you cannot be bothered to read all the nitty-gritty details about futures, but just want to try them out, then skip to the end to play with the Mandelbrot demo using both parallel and non-parallel evaluation.
+
+
+
+## Implicit or Explicit Futures
+
+Futures can be created either _implicitly_ or _explicitly_. In the introductory example above we used _implicit futures_ created via the `v %<-% { expr }` construct. An alternative is _explicit futures_ using the `f <- future({ expr })` and `v <- value(f)` constructs. With these, our example could alternatively be written as:
+```r
+> library("future")
+> f <- future({
++ cat("Resolving...\n")
++ 3.14
++ })
+Resolving...
+> v <- value(f)
+> v
+[1] 3.14
+```
+
+Either style of future construct works equally(*) well. The implicit style is most similar to how regular R code is written. In principle, all you have to do is to replace `<-` with a `%<-%` to turn the assignment into a future assignment. On the other hand, this simplicity can also be deceiving, particularly when asynchronous futures are being used. In contrast, the explicit style makes it much clearer that futures are being used, which lowers the risk for mistakes and better commun [...]
+
+(*) There are cases where `%<-%` cannot be used without some (small) modifications. We will return to this in Section 'Constraints when using Implicit Futures' near the end of this document.
+
+
+
+To summarize, for explicit futures, we use:
+
+* `f <- future({ expr })` - creates a future
+* `v <- value(f)` - gets the value of the future (blocks if not yet resolved)
+
+For implicit futures, we use:
+
+* `v %<-% { expr }` - creates a future and a promise to its value
+
+To keep it simple, we will use the implicit style in the rest of this document, but everything discussed will also apply to explicit futures.
+
+
+
+## Controlling How Futures are Resolved
+The future package implements the following types of futures:
+
+| Name | OSes | Description
+|:----------------|:------------|:-----------------------------------------------------
+| _synchronous:_ | | _non-parallel:_
+| `eager` | all |
+| `lazy` | all | lazy evaluation - happens only if the value is requested
+| `transparent` | all | for debugging (eager w/ early signaling and w/out local)
+| _asynchronous:_ | | _parallel_:
+| `multiprocess` | all | multicore iff supported, otherwise multisession
+| `multisession` | all | background R sessions (on current machine)
+| `multicore` | not Windows | forked R processes (on current machine)
+| `cluster` | all | external R sessions on current, local, and/or remote machines
+| `remote` | all | Simple access to remote R sessions
+
+The future package is designed such that support for additional strategies can be implemented as well. For instance, the [future.BatchJobs] package provides futures for all types of _cluster functions_ ("backends") that the [BatchJobs] package supports. Specifically, futures for evaluating R expressions via job schedulers such as Slurm, TORQUE/PBS, Oracle/Sun Grid Engine (SGE) and Load Sharing Facility (LSF) are also available.
+
+By default, future expressions are evaluated instantaneously and synchronously (in the current R session). This evaluation strategy is referred to as "eager" and we refer to futures using this strategy as "eager futures". In this section, we will go through each of these strategies and discuss what they have in common and how they differ.
+
+
+### Consistent Behavior Across Futures
+Before going through each of the different future strategies, it is probably helpful to clarify the objectives the Future API (as defined by the future package). When programming with futures, it should not really matter what future strategy is used for executing code. This is because we cannot really know what computational resources the user has access to so the choice of evaluation strategy should be in the hand of the user and not the developer. In other words, the code should not [...]
+
+One of the designs of the Future API was to encapsulate any differences such that all types of futures will appear to work the same. This despite expressions may be evaluated locally in the current R session or across the world in remote R sessions. Another obvious advantage of having a consistent API and behavior among different types of futures is that it helps while prototyping. Typically one would use eager evaluation while building up a script and, later, when the script is fully [...]
+
+Because of this, the defaults of the different strategies are such that the results and side effects of evaluating a future expression are as similar as possible. More specifically, the following is true for all futures:
+
+* All _evaluation is done in a local environment_ (i.e. `local({ expr })`) such assignments do not affect the calling environment. This is natural when evaluating in an external R process, but is also enforced when evaluating in the current R session.
+
+* When a future is constructed, _global variables are identified_. For asynchronous evaluation, globals are exported to the R process/session that will be evaluating the future expression. For lazy futures, globals are "frozen" (cloned to a local environment of the future). Also, in order to protect against exporting too large objects by mistake, there is a built-in assertion that the total size of all globals is less than a given threshold (controllable via an option, cf. `help("futu [...]
+
+* Future _expressions are only evaluated once_. As soon as the value (or an error) has been collected it will be available for all succeeding requests.
+
+Here is an example illustrating that all assignments are done to a local environment:
+```r
+> plan(eager)
+> a <- 1
+> x %<-% {
++ a <- 2
++ 2 * a
++ }
+> x
+[1] 4
+> a
+[1] 1
+```
+
+
+Now we are ready to explore the different future strategies.
+
+
+### Synchronous Futures
+
+Synchronous futures are resolved one after another and most commonly by the R process that creates them. When a synchronous future is being resolved it blocks the main process until resolved. There are two main types of synchronous futures in the future package, _eager_ and _lazy_ futures, which are described next.
+
+
+#### Eager Futures
+Eager futures are the default unless otherwise specified. They were designed to behave as similar as possible to regular R evaluation while still fulfilling the Future API and its behaviors. Here is an example illustrating their properties:
+```r
+> plan(eager)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+Resolving 'a' ...
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+Resolving 'b' ...
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+Resolving 'c' ...
+> b
+[1] 28072
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+Since eager evaluation is taking place, each of the three futures is resolved instantaneously in the moment it is created. Note also how `pid` in the calling environment, which was assigned the process ID of the current process, is neither overwritten nor removed. This is because futures are evaluated in a local environment. Since synchronous (uni-)processing is used, future `b` is resolved by the main R process (still in a local environment), which is why the value of `b` and `pid` a [...]
+
+
+#### Lazy Futures
+A lazy future evaluates its expression only if its value is queried. Evaluation can also be triggered when the future is checked for being resolved or not. Here is the above example when using lazy evaluation:
+```r
+> plan(lazy)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+Resolving 'a' ...
+> b
+Resolving 'b' ...
+[1] 28072
+> c
+Resolving 'c' ...
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+As previously, variable `pid` is unaffected because all evaluation is done in a local environment. More interestingly, future `a` is no longer evaluated in the moment it is created, but instead when it is needed the first time, which happens when future `c` is created. This is because `a` is identified as a global variable that needs to be captured ("frozen" to `a == 3.14`) in order to set up future `c`. Later when `c` (the value of future `c`) is queried, `a` has already been resolve [...]
+
+_Comment_: Lazy evaluation is already used by R itself. Arguments are passed to functions using lazy evaluation. It is also possible to assign variables using lazy evaluation using `delayedAssign()`, but contrary to lazy futures this function does not freeze globals. For more information, see `help("delayedAssign", package="base")`.
+
+
+
+
+
+
+
+### Asynchronous Futures
+Next, we will turn to asynchronous futures, which are futures that are resolved in the background. By design, these futures are non-blocking, that is, after being created the calling process is available for other tasks including creating additional futures. It is only when the calling process tries to access the value of a future that is not yet resolved, or trying to create another asynchronous future when all available R processes are busy serving other futures, that it blocks.
+
+
+#### Multisession Futures
+We start with multisession futures because they are supported by all operating systems. A multisession future is evaluated in a background R session running on the same machine as the calling R process. Here is our example with multisession evaluation:
+```r
+> plan(multisession)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+> b
+[1] 28093
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+The first thing we observe is that the values of `a`, `c` and `pid` are the same as previously. However, we notice that `b` is different from before. This is because future `b` is evaluated in a different R process and therefore it returns a different process ID. Another difference is that the messages, generated by `cat()`, are no longer displayed. This is because they are outputted to the background sessions and not the calling session.
+
+
+When multisession evaluation is used, the package launches a set of R sessions in the background that will serve multisession futures by evaluating their expressions as they are created. If all background sessions are busy serving other futures, the creation of the next multisession future is _blocked_ until a background session becomes available again. The total number of background processes launched is decided by the value of `availableCores()`, e.g.
+```r
+> availableCores()
+mc.cores+1
+ 3
+```
+This particular result tells us that the `mc.cores` option was set such that we are allowed to use in total 3 processes including the main process. In other words, with these settings, there will be 2 background processes serving the multisession futures. The `availableCores()` is also agile to different options and system environment variables. For instance, if compute cluster schedulers are used (e.g. TORQUE/PBS and Slurm), they set specific environment variable specifying the numbe [...]
+
+
+#### Multicore Futures
+On operating systems where R supports _forking_ of processes, which is basically all operating system except Windows, an alternative to spawning R sessions in the background is to fork the existing R process. Forking an R process is considered faster than working with a separate R session running in the background. One reason is that the overhead of exporting large globals to the background session can be greater than when forking is used.
+To use multicore futures, we specify:
+```r
+plan(multicore)
+```
+The only real different between using multicore and multisession futures is that any output written (to standard output or standard error) by a multicore process is instantaneously outputted in calling process. Other than this, the behavior of using multicore evaluation is very similar to that of using multisession evaluation.
+
+Just like for multisession futures, the maximum number of parallel processes running will be decided by `availableCores()`, since in both cases the evaluation is done on the local machine.
+
+
+
+#### Multiprocess Futures
+Sometimes we do not know whether multicore futures are supported or not, but it might still be that we would like to write platform-independent scripts or instructions that work everywhere. In such cases we can specify that we want to use "multiprocess" futures as in:
+```r
+plan(multiprocess)
+```
+A multiprocess future is not a formal class of futures by itself, but rather a convenient alias for either of the two. When this is specified, multisession evaluation will be used unless multicore evaluation is supported.
+
+
+#### Cluster Futures
+Cluster futures evaluate expressions on an ad-hoc cluster (as implemented by the parallel package). For instance, assume you have access to three nodes `n1`, `n2` and `n3`, you can then use these for asynchronous evaluation as:
+```r
+> plan(cluster, workers = c("n1", "n2", "n3"))
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+> b
+[1] 28115
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+Just as for the other asynchronous evaluation strategies, the output from `cat()` is not displayed on the current/calling machine.
+
+
+Any types of clusters that `parallel::makeCluster()` creates can be used for cluster futures. For instance, the above cluster can be explicitly set up as:
+```r
+cl <- parallel::makeCluster(c("n1", "n2", "n3"))
+plan(cluster, workers=cl)
+```
+Also, it is considered good style to shut down the cluster when it is no longer needed, that is, calling `parallel::stopCluster(cl)`. However, it will shut itself down if the main process is terminated, which will happen in the first example where the cluster in created internally. For more information on how to set up and manage such clusters, see `help("makeCluster", package="parallel")`.
+
+Note that with proper firewall and router configurations (e.g. port forwarding) and with automatic authentication setup (e.g. SSH key pairs), there is nothing preventing us from using the same approach for using a cluster of remote machines.
+
+
+
+### Different Strategies for Different Futures
+Sometimes one may want to use an alternative evaluation strategy for a specific future. Although one can use `old <- plan(new)` and afterward `plan(old)` to temporarily switch strategies, a simpler approach is to use the `%plan%` operator, e.g.
+```r
+> plan(eager)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ Sys.getpid()
++ }
+> b %<-% {
++ Sys.getpid()
++ } %plan% multiprocess
+> c %<-% {
++ Sys.getpid()
++ } %plan% multiprocess
+> a
+[1] 28072
+> b
+[1] 28132
+> c
+[1] 28133
+```
+As seen by the different process IDs, future `a` is evaluated eagerly using the same process as the calling environment whereas the other two are evaluated using multiprocess futures.
+
+
+
+
+However, using different plans to individual futures this way has the drawback of hard coding the evaluation strategy. Doing so may prevent some users from using your script or your package, because they do not have the sufficient resources. It may also prevent users with a lot of resources from utilizing those because you assumed a less-powerful set of hardware. Because of this, we recommend against the use of `%plan%` other than for interactive prototyping.
+
+
+### Nested Futures and Evaluation Topologies
+This far we have discussed what can be referred to as "flat topology" of futures, that is, all futures are created in and assigned to the same environment. However, there is nothing stopping us from using a "nested topology" of futures, where one set of futures may, in turn, create another set of futures internally and so on.
+
+For instance, here is an example of two "top" futures (`a` and `b`) that uses multiprocess evaluation and where the second future (`b`) in turn uses two internal futures:
+```r
+> plan(multiprocess)
+> pid <- Sys.getpid()
+> a %<-% {
++ cat("Resolving 'a' ...\n")
++ Sys.getpid()
++ }
+> b %<-% {
++ cat("Resolving 'b' ...\n")
++ b1 %<-% {
++ cat("Resolving 'b1' ...\n")
++ Sys.getpid()
++ }
++ b2 %<-% {
++ cat("Resolving 'b2' ...\n")
++ Sys.getpid()
++ }
++ c(b.pid = Sys.getpid(), b1.pid = b1, b2.pid = b2)
++ }
+> pid
+[1] 28072
+> a
+[1] 28134
+> b
+ b.pid b1.pid b2.pid
+ 28135 28135 28135
+```
+By inspection the process IDs, we see that there are in total three different processes involved for resolving the futures. There is the main R process (pid 28072), and there are the two processes used by `a` (pid 28134) and `b` (pid 28135). However, the two futures (`b1` and `b2`) that is nested by `b` are evaluated by the same R process as `b`. This is because nested futures use eager evaluation unless otherwise specified. There are a few reasons for this, but the main reason is th [...]
+
+
+
+To specify a different type of _evaluation topology_, other than the first level of futures being resolved by multiprocess evaluation and the second level by eager evaluation, we can provide a list of evaluation strategies to `plan()`. First, the same evaluation strategies as above can be explicitly specified as:
+```r
+plan(list(multiprocess, eager))
+```
+We would actually get the same behavior if we try with multiple levels of multiprocess evaluations;
+```r
+> plan(list(multiprocess, multiprocess))
+[...]
+> pid
+[1] 28072
+> a
+[1] 28136
+> b
+ b.pid b1.pid b2.pid
+ 28137 28137 28137
+```
+The reason for this is, also here, to protect us from launching more processes than what the machine can support. Internally, this is done by setting `mc.cores` to zero ([sic!](https://github.com/HenrikBengtsson/Wishlist-for-R/issues/7)) such that no _additional_ parallel processes can be launched. This is the case for both multisession and multicore evaluation.
+
+
+Continuing, if we start off by eager evaluation and then use multiprocess evaluation for any nested futures, we get:
+```r
+> plan(list(eager, multiprocess))
+[...]
+Resolving 'a' ...
+Resolving 'b' ...
+> pid
+[1] 28072
+> a
+[1] 28072
+> b
+ b.pid b1.pid b2.pid
+ 28072 28138 28139
+```
+which clearly show that `a` and `b` are resolved in the calling process (pid 28072) whereas the two nested futures (`b1` and `b2`) are resolved in two separate R processes (pids 28138 and 28139).
+
+
+
+Having said this, it is indeed possible to use nested multiprocess evaluation strategies, if we explicitly specify (read _force_) the number of cores available at each level. In order to do this we need to "tweak" the default settings, which can be done as follows:
+```r
+> plan(list(tweak(multiprocess, workers = 3), tweak(multiprocess,
++ workers = 3)))
+[...]
+> pid
+[1] 28072
+> a
+[1] 28140
+> b
+ b.pid b1.pid b2.pid
+ 28141 28142 28145
+```
+First, we see that both `a` and `b` are resolved in different processes (pids 28140 and 28141) than the calling process (pid 28072). Second, the two nested futures (`b1` and `b2`) are resolved in yet two other R processes (pids 28142 and 28145).
+
+
+To clarify, when we set up the two levels of multiprocess evaluation, we specified that in total 3 processes may be used at each level. We choose three parallel processes, not just two, because one is always consumed by the calling process leaving two to be used for the asynchronous futures. This is why we see that `pid`, `a` and `b` are all resolved by the same process. If we had allowed only two cores at the top level, `a` and `b` would have been resolved by the same background proc [...]
+
+For more details on working with nested futures and different evaluation strategies at each level, see Vignette '[Futures in R: Future Topologies]'.
+
+
+### Checking A Future without Blocking
+It is possible to check whether a future has been resolved or not without blocking. This can be done using the `resolved(f)` function, which takes an explicit future `f` as input. If we work with implicit futures (as in all the examples above), we can use the `f <- futureOf(a)` function to retrieve the explicit future from an implicit one. For example,
+```r
+> plan(multiprocess)
+> a %<-% {
++ cat("Resolving 'a' ...")
++ Sys.sleep(2)
++ cat("done\n")
++ Sys.getpid()
++ }
+> cat("Waiting for 'a' to be resolved ...\n")
+Waiting for 'a' to be resolved ...
+> f <- futureOf(a)
+> count <- 1
+> while (!resolved(f)) {
++ cat(count, "\n")
++ Sys.sleep(0.2)
++ count <- count + 1
++ }
+1
+2
+3
+4
+5
+> cat("Waiting for 'a' to be resolved ... DONE\n")
+Waiting for 'a' to be resolved ... DONE
+> a
+[1] 28146
+```
+
+
+## Failed Futures
+Sometimes the future is not what you expected. If an error occurs while evaluating a future, the error is propagated and thrown as an error in the calling environment _when the future value is requested_. For example,
+```r
+> plan(lazy)
+> a %<-% {
++ cat("Resolving 'a' ...\n")
++ stop("Whoops!")
++ 42
++ }
+> cat("Everything is still ok although we have created a future that will fail.\n")
+Everything is still ok although we have created a future that will fail.
+> a
+Resolving 'a' ...
+Error in eval(expr, envir, enclos) : Whoops!
+```
+The error is thrown each time the value is requested, that is, if we try to get the value again will generate the same error:
+```r
+> a
+Error in eval(expr, envir, enclos) : Whoops!
+In addition: Warning message:
+restarting interrupted promise evaluation
+```
+To see the list of calls (evaluated expressions) that lead up to the error, we can use the `backtrace()` function(*) on the future, i.e.
+```r
+> backtrace(a)
+[[1]]
+eval(quote({
+ cat("Resolving 'a' ...\n")
+ stop("Whoops!")
+ 42
+}), new.env())
+[[2]]
+eval(expr, envir, enclos)
+[[3]]
+stop("Whoops!")
+```
+(*) The commonly used `traceback()` does not provide relevant information in the context of futures.
+
+
+## Globals
+Whenever an R expression is to be evaluated asynchronously (in parallel) or via lazy evaluation, global objects have to be identified and passed to the evaluator. They need to be passed exactly as they were at the time the future was created, because, for a lazy future, globals may otherwise change between when it is created and when it is resolved. For asynchronous processing, the reason globals need to be identified is so that they can be exported to the process that evaluates the future.
+
+The future package tries to automate these tasks as far as possible. It does this with help of the [globals] package. If a global variable is identified, it is captured and made available to the evaluating process.
+Moreover, if a global is defined in a package, then that global is not exported. Instead, it is made sure that the corresponding package is attached when the future is evaluated. This not only better reflects the setup of the main R session, but it also minimizes the need for exporting globals, which saves not only memory but also time and bandwidth, especially when using remote compute nodes.
+
+Finally, it should be clarified that identifying globals from static code inspection alone is a challenging problem. There will always be corner cases where automatic identification of globals fails so that either false globals are identified (less of a concern) or some of the true globals are missing (which will result in a runtime error or possibly the wrong results). Vignette '[Futures in R: Common Issues with Solutions]' provides examples of common cases and explains how to avoid t [...]
+
+
+
+## Constraints when using Implicit Futures
+
+There is one limitation with implicit futures that does not exist for explicit ones. Because an explicit future is just like any other object in R it can be assigned anywhere/to anything. For instance, we can create several of them in a loop and assign them to a list, e.g.
+```r
+> plan(multiprocess)
+> f <- list()
+> for (ii in 1:3) {
++ f[[ii]] <- future({
++ Sys.getpid()
++ })
++ }
+> v <- lapply(f, FUN = value)
+> str(v)
+List of 3
+ $ : int 28147
+ $ : int 28148
+ $ : int 28149
+```
+This is _not_ possible to do when using implicit futures. This is because the `%<-%` assignment operator _cannot_ be used in all cases where the regular `<-` assignment operator can be used. It can only be used to assign future values to _environments_ (including the calling environment) much like how `assign(name, value, envir)` works. However, we can assign implicit futures to environments using _named indices_, e.g.
+```r
+> plan(multiprocess)
+> v <- new.env()
+> for (name in c("a", "b", "c")) {
++ v[[name]] %<-% {
++ Sys.getpid()
++ }
++ }
+> v <- as.list(v)
+> str(v)
+List of 3
+ $ a: int 28150
+ $ b: int 28151
+ $ c: int 28152
+```
+Here `as.list(v)` blocks until all futures in the environment `v` have been resolved. Then their values are collected and returned as a regular list.
+
+If _numeric indices_ are required, then _list environments_ can be used. List environments, which are implemented by the [listenv] package, are regular environments with customized subsetting operators making it possible to index them much like how lists can be indexed. By using list environments where we otherwise would use lists, we can also assign implicit futures to list-like objects using numeric indices. For example,
+```r
+> library("listenv")
+> plan(multiprocess)
+> v <- listenv()
+> for (ii in 1:3) {
++ v[[ii]] %<-% {
++ Sys.getpid()
++ }
++ }
+> v <- as.list(v)
+> str(v)
+List of 3
+ $ : int 28153
+ $ : int 28154
+ $ : int 28155
+```
+As previously, `as.list(v)` blocks until all futures are resolved.
+
+
+
+## Demos
+To see a live illustration how different types of futures are evaluated, run the Mandelbrot demo of this package. First, try with the eager evaluation,
+```r
+library("future")
+plan(eager)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+which closely imitates how the script would run if futures were not used. Then try the same using lazy evaluation,
+```r
+plan(lazy)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+and see if you can notice the difference in how and when statements are evaluated.
+You may also try multiprocess evaluation, which calculates the different Mandelbrot planes using parallel R processes running in the background. Try,
+```r
+plan(multiprocess)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+This will use multicore processing if you are on a system where R supports process forking, otherwise (such as on Windows) it will use multisession processing.
+
+Finally, if you have access to multiple machines you can try to set up a cluster of workers and use them, e.g.
+```r
+plan(cluster, workers=c("n2", "n5", "n6", "n6", "n9"))
+demo("mandelbrot", package="future", ask=FALSE)
+```
+
+
+
+## Contributing
+The goal of this package is to provide a standardized and unified API for using futures in R. What you are seeing right now is an early but sincere attempt to achieve this goal. If you have comments or ideas on how to improve the 'future' package, I would love to hear about them. The preferred way to get in touch is via the [GitHub repository](https://github.com/HenrikBengtsson/future/), where you also find the latest source code. I am also open to contributions and collaborations of [...]
+
+
+[BatchJobs]: http://cran.r-project.org/package=BatchJobs
+[future]: http://cran.r-project.org/package=future
+[future.BatchJobs]: http://cran.r-project.org/package=future.BatchJobs
+[globals]: http://cran.r-project.org/package=globals
+[listenv]: http://cran.r-project.org/package=listenv
+[Futures in R: Common Issues with Solutions]: future-2-issues.html
+[Futures in R: Future Topologies]: future-3-topologies.html
+
+## Installation
+R package future is available on [CRAN](http://cran.r-project.org/package=future) and can be installed in R as:
+```r
+install.packages('future')
+```
+
+### Pre-release version
+
+To install the pre-release version that is available in branch `develop`, use:
+```r
+source('http://callr.org/install#HenrikBengtsson/future@develop')
+```
+This will install the package from source.
+
+
+
+## Software status
+
+| Resource: | CRAN | Travis CI | Appveyor |
+| ------------- | ------------------- | -------------- | ---------------- |
+| _Platforms:_ | _Multiple_ | _Linux & OS X_ | _Windows_ |
+| R CMD check | <a href="http://cran.r-project.org/web/checks/check_results_future.html"><img border="0" src="http://www.r-pkg.org/badges/version/future" alt="CRAN version"></a> | <a href="https://travis-ci.org/HenrikBengtsson/future"><img src="https://travis-ci.org/HenrikBengtsson/future.svg" alt="Build status"></a> | <a href="https://ci.appveyor.com/project/HenrikBengtsson/future"><img src="https://ci.appveyor.com/api/projects/status/github/HenrikBengtsson/future?svg=true" alt="Buil [...]
+| Test coverage | | <a href="https://codecov.io/gh/HenrikBengtsson/future"><img src="https://codecov.io/gh/HenrikBengtsson/future/branch/develop/graph/badge.svg" alt="Coverage Status"/></a> | |
diff --git a/appveyor.yml b/appveyor.yml
new file mode 100644
index 0000000..73fcf83
--- /dev/null
+++ b/appveyor.yml
@@ -0,0 +1,72 @@
+#----------------------------------------------------------------
+# AppVeyor configuration for R packages
+#
+# REFERENCES:
+# * AppVeyor CI: https://ci.appveyor.com/
+# * r-appveyor: https://github.com/krlmlr/r-appveyor
+#
+# Validate your .appveyor.yml file at
+# https://ci.appveyor.com/tools/validate-yaml
+#----------------------------------------------------------------
+environment:
+ _R_CHECK_FORCE_SUGGESTS_: false
+
+ matrix:
+ - R_VERSION: devel
+ R_ARCH: x64
+
+ - R_VERSION: devel
+ R_ARCH: i386
+
+# - R_VERSION: release
+# R_ARCH: x64
+
+
+# DO NOT CHANGE the "init" and "install" sections below
+
+# Download script file from GitHub
+init:
+ ps: |
+ $ErrorActionPreference = "Stop"
+ Invoke-WebRequest http://raw.github.com/krlmlr/r-appveyor/master/scripts/appveyor-tool.ps1 -OutFile "..\appveyor-tool.ps1"
+ Import-Module '..\appveyor-tool.ps1'
+install:
+ ps: |
+ Bootstrap
+ InstallRtools
+
+# Adapt as necessary starting from here
+
+build_script:
+ - echo Current directory=%CD%
+ - travis-tool.sh install_r digest globals listenv markdown
+ - travis-tool.sh install_r R.rsp
+
+test_script:
+ - travis-tool.sh run_tests
+
+after_test:
+ - 7z a all-Rout.zip *.Rcheck\**\*.Rout *.Rcheck\**\*.fail
+
+artifacts:
+ - path: '*.Rcheck\**\*.log'
+ name: Logs
+
+ - path: '*.Rcheck\**\*.out'
+ name: Logs
+
+ - path: '*.Rcheck\**\*.fail'
+ name: Logs
+
+ - path: '\*_*.tar.gz'
+ name: Bits
+
+ - path: '\*_*.zip'
+ name: Bits
+
+ - path: all-Rout.zip
+ name: AllRout
+
+on_failure:
+ - 7z a failure.zip *.Rcheck\*
+ - appveyor PushArtifact failure.zip
diff --git a/build/vignette.rds b/build/vignette.rds
deleted file mode 100644
index 7405d6d..0000000
Binary files a/build/vignette.rds and /dev/null differ
diff --git a/cran-comments.md b/cran-comments.md
new file mode 100644
index 0000000..849884d
--- /dev/null
+++ b/cran-comments.md
@@ -0,0 +1,49 @@
+# CRAN submission future 1.0.1
+on 2015-07-04
+
+Updates related to CRAN:
+
+* Package failed on CRAN under r-devel-osx-x86_64-clang (only),
+ because test code incorrectly assumed system("Rscript") would
+ launch the same executable as the running R session.
+
+Thanks in advance
+
+
+## Notes not sent to CRAN
+The package has been verified using `R CMD check --as-cran` on:
+
+* Platform x86_64-apple-darwin13.4.0 (64-bit) [Travis CI]:
+ - R 3.2.4 Revised (2016-03-16)
+ - R version 3.3.1 (2016-06-21)
+
+* Platform x86_64-unknown-linux-gnu (64-bit) [Travis CI]:
+ - R version 3.2.5 (2016-04-14)
+ - R version 3.3.1 (2016-06-21)
+ - R Under development (unstable) (2016-06-30 r70858)
+
+* Platform x86_64-pc-linux-gnu (64-bit):
+ - R version 3.1.3 (2015-03-09)
+ - R version 3.2.5 (2016-04-14)
+ - R version 3.3.0 (2016-05-03)
+ - R version 3.3.1 (2016-06-21)
+ - R version 3.3.1 Patched (2016-06-28 r70858)
+ - R Under development (unstable) (2016-06-30 r70858)
+
+* Platform i686-pc-linux-gnu (32-bit):
+ - R version 3.3.1 (2016-06-21)
+
+* Platform i386-w64-mingw32 (32-bit) [Appveyor CI]:
+ - R Under development (unstable) (2016-06-22 r70818)
+
+* Platform x86_64-w64-mingw32/x64 (64-bit) [Appveyor CI]:
+ - R Under development (unstable) (2016-06-22 r70818)
+
+* Platform x86_64-w64-mingw32/x64 (64-bit) [win-builder]:
+ - R version 3.3.1 (2016-06-21)
+ - R Under development (unstable) (2016-06-24 r70828)
+
+The submitted updates cause no issues for any of the following
+7 reverse dependencies on CRAN and Bioconductor: PSCBS 0.61.0,
+QDNAseq 1.8.0, R.filesets 2.10.0, aroma.affymetrix 3.0.0,
+aroma.core 3.0.0, doFuture 0.2.0, and future.BatchJobs 0.12.1.
diff --git a/incl/cluster.R b/incl/cluster.R
new file mode 100644
index 0000000..3850c7d
--- /dev/null
+++ b/incl/cluster.R
@@ -0,0 +1,33 @@
+## Cluster futures gives an error on R CMD check on
+## Windows (but not Linux or OS X) for unknown reasons.
+## The same code works in package tests.
+\donttest{
+
+## Use cluster futures
+cl <- parallel::makeCluster(2L)
+plan(cluster, workers=cl)
+
+## A global variable
+a <- 0
+
+## Create multicore future (explicitly)
+f <- future({
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+## A cluster future is evaluated in a separate process.
+## 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)
+
+## CLEANUP
+parallel::stopCluster(cl)
+
+}
diff --git a/incl/eager.R b/incl/eager.R
new file mode 100644
index 0000000..3f7db4a
--- /dev/null
+++ b/incl/eager.R
@@ -0,0 +1,22 @@
+## Use eager futures
+plan(eager)
+
+## A global variable
+a <- 0
+
+## Create eager future (explicitly)
+f <- future({
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+## Since 'a' is a global variable in _eager_ future 'f',
+## it already has been resolved, and any changes to 'a'
+## at this point will _not_ affect the value of 'f'.
+a <- 7
+print(a)
+
+v <- value(f)
+print(v)
+stopifnot(v == 0)
diff --git a/incl/future.R b/incl/future.R
new file mode 100644
index 0000000..ed2a5da
--- /dev/null
+++ b/incl/future.R
@@ -0,0 +1,13 @@
+## Use lazy futures
+plan(lazy)
+
+f <- future({
+ a <- 7
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+print(resolved(f))
+y <- value(f)
+print(y)
diff --git a/incl/futureAssign_OP.R b/incl/futureAssign_OP.R
new file mode 100644
index 0000000..efee987
--- /dev/null
+++ b/incl/futureAssign_OP.R
@@ -0,0 +1,32 @@
+## Future assignment via "assign" function
+futureAssign("A", {
+ x <- 3
+ x^2
+})
+cat("Value 'A': ", A, sep="")
+
+
+## Equivalent via infix "assign" operator
+A %<-% {
+ x <- 3
+ x^2
+}
+cat("Value 'A': ", A, sep="")
+
+
+## A global variable
+a <- 1
+
+## Three future evaluations
+A %<-% { 0.1 }
+B %<-% { 0.2 }
+C %<-% { z <- a+0.3 }
+
+## Sleep until 'C' is available
+cat("Value 'C': ", C, sep="")
+
+## Sleep until 'A' is available
+cat("Value 'A': ", A, sep="")
+
+## Sleep until 'C' is available
+cat("Value 'B': ", B, sep="")
diff --git a/incl/futureOf.R b/incl/futureOf.R
new file mode 100644
index 0000000..5f9cf4b
--- /dev/null
+++ b/incl/futureOf.R
@@ -0,0 +1,33 @@
+a %<-% { 1 }
+
+f <- futureOf(a)
+print(f)
+
+b %<-% { 2 }
+
+f <- futureOf(b)
+print(f)
+
+## All futures
+fs <- futureOf()
+print(fs)
+
+
+## Futures part of environment
+env <- new.env()
+env$c %<-% { 3 }
+
+f <- futureOf(env$c)
+print(f)
+
+f2 <- futureOf(c, envir=env)
+print(f2)
+
+f3 <- futureOf("c", envir=env)
+print(f3)
+
+fs <- futureOf(envir=env)
+print(fs)
+
+
+
diff --git a/incl/lazy.R b/incl/lazy.R
new file mode 100644
index 0000000..ca262c9
--- /dev/null
+++ b/incl/lazy.R
@@ -0,0 +1,60 @@
+## Use lazy futures
+plan(lazy)
+
+## A global variable
+a <- 0
+
+## Create lazy future (explicitly)
+f <- future({
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+## Although 'f' is a _lazy_ future and therefore
+## resolved/evaluates the future expression only
+## when the value is requested, any global variables
+## identified in the expression (here 'a') are
+## "frozen" at the time point when the future is
+## created. Because of this, the 'a' in the
+## the future expression preserved the zero value
+## although we reassign it in the global environment
+a <- 7
+print(a)
+
+v <- value(f)
+print(v)
+stopifnot(v == 0)
+
+
+## Another example illustrating that lazy futures go
+## hand-in-hand with lazy evaluation of arguments
+
+## A function that may or may not touch it's argument
+foo <- function(a, use=FALSE) {
+ cat("foo() called\n")
+ if (use) cat("a=", a, "\n", sep="")
+}
+
+## Create a future
+x %<-% { cat("Pow!\n"); 1 }
+
+## Lazy evaluation where argument is not used
+foo(x, use=FALSE)
+# Outputs:
+# foo() called
+
+## Lazy evaluation where argument is used
+## Hint: 'x' will be resolved
+foo(x, use=TRUE)
+# Outputs:
+# foo() called
+# Pow!
+# a=1
+
+## Lazy evaluation where argument is used (again)
+## Hint: 'x' is already resolved
+foo(x, use=TRUE)
+# Outputs:
+# foo() called
+# a=1
diff --git a/incl/mandelbrot.R b/incl/mandelbrot.R
new file mode 100644
index 0000000..d214b0d
--- /dev/null
+++ b/incl/mandelbrot.R
@@ -0,0 +1,6 @@
+counts <- mandelbrot(x=-0.75, y=0, side=3)
+plot(counts)
+
+\dontrun{
+demo("mandelbrot", package="future", ask=FALSE)
+}
diff --git a/incl/multicore.R b/incl/multicore.R
new file mode 100644
index 0000000..04bb746
--- /dev/null
+++ b/incl/multicore.R
@@ -0,0 +1,22 @@
+## Use multicore futures
+plan(multicore)
+
+## A global variable
+a <- 0
+
+## Create multicore future (explicitly)
+f <- future({
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+## A multicore future is evaluated in a separate forked
+## process. 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)
diff --git a/incl/multiprocess.R b/incl/multiprocess.R
new file mode 100644
index 0000000..4ffd7d0
--- /dev/null
+++ b/incl/multiprocess.R
@@ -0,0 +1,29 @@
+## Multiprocess futures gives an error on R CMD check on
+## Windows (but not Linux or OS X) for unknown reasons.
+## The same code works in package tests.
+\donttest{
+
+## Use multiprocess futures
+plan(multiprocess)
+
+## A global variable
+a <- 0
+
+## Create multicore future (explicitly)
+f <- future({
+ b <- 3
+ c <- 2
+ a * b * c
+})
+
+## A multiprocess future is evaluated in a separate R process.
+## 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)
+
+}
diff --git a/incl/multisession.R b/incl/multisession.R
new file mode 100644
index 0000000..c43b3d7
--- /dev/null
+++ b/incl/multisession.R
@@ -0,0 +1,29 @@
+## Multisession futures gives an error on R CMD check on
+## Windows (but not Linux or OS X) for unknown reasons.
+## The same code works in package tests.
+\donttest{
+
+## Use multisession futures
+plan(multisession)
+
+## A global variable
+a <- 0
+
+## Create multicore 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)
+
+}
diff --git a/incl/plan.R b/incl/plan.R
new file mode 100644
index 0000000..541fef3
--- /dev/null
+++ b/incl/plan.R
@@ -0,0 +1,59 @@
+a <- b <- c <- NA_real_
+
+# A lazy future
+plan(lazy)
+f <- future({
+ a <- 7
+ b <- 3
+ c <- 2
+ a * b * c
+})
+y <- value(f)
+print(y)
+str(list(a=a, b=b, c=c)) ## All NAs
+
+
+# An eager future
+plan(eager)
+f <- future({
+ a <- 7
+ b <- 3
+ c <- 2
+ a * b * c
+})
+y <- value(f)
+print(y)
+str(list(a=a, b=b, c=c)) ## All NAs
+
+
+# A multicore future
+plan(multicore)
+f <- future({
+ a <- 7
+ b <- 3
+ c <- 2
+ a * b * c
+})
+y <- value(f)
+print(y)
+str(list(a=a, b=b, c=c)) ## All NAs
+
+
+## Multisession futures gives an error on R CMD check on
+## Windows (but not Linux or OS X) for unknown reasons.
+## The same code works in package tests.
+\donttest{
+
+# A multisession future
+plan(multisession)
+f <- future({
+ a <- 7
+ b <- 3
+ c <- 2
+ a * b * c
+})
+y <- value(f)
+print(y)
+str(list(a=a, b=b, c=c)) ## All NAs
+
+}
diff --git a/incl/remote.R b/incl/remote.R
new file mode 100644
index 0000000..476339b
--- /dev/null
+++ b/incl/remote.R
@@ -0,0 +1,11 @@
+\dontrun{\donttest{
+
+## Use a remote machine
+plan(remote, workers="remote.server.org")
+
+## Evaluate expression remotely
+host %<-% { Sys.info()[["nodename"]] }
+host
+[1] "remote.server.org"
+
+}}
diff --git a/inst/doc/future-1-overview.html b/inst/doc/future-1-overview.html
deleted file mode 100644
index 7c8374f..0000000
--- a/inst/doc/future-1-overview.html
+++ /dev/null
@@ -1,881 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
-
-<title>A Future for R: A Comprehensive Overview</title>
-
-<script type="text/javascript">
-window.onload = function() {
- var imgs = document.getElementsByTagName('img'), i, img;
- for (i = 0; i < imgs.length; i++) {
- img = imgs[i];
- // center an image if it is the only element of its parent
- if (img.parentElement.childElementCount === 1)
- img.parentElement.style.textAlign = 'center';
- }
-};
-</script>
-
-<!-- Styles for R syntax highlighter -->
-<style type="text/css">
- pre .operator,
- pre .paren {
- color: rgb(104, 118, 135)
- }
-
- pre .literal {
- color: #990073
- }
-
- pre .number {
- color: #099;
- }
-
- pre .comment {
- color: #998;
- font-style: italic
- }
-
- pre .keyword {
- color: #900;
- font-weight: bold
- }
-
- pre .identifier {
- color: rgb(0, 0, 0);
- }
-
- pre .string {
- color: #d14;
- }
-</style>
-
-<!-- R syntax highlighter -->
-<script type="text/javascript">
-var hljs=new function(){function m(p){return p.replace(/&/gm,"&").replace(/</gm,"<")}function f(r,q,p){return RegExp(q,"m"+(r.cI?"i":"")+(p?"g":""))}function b(r){for(var p=0;p<r.childNodes.length;p++){var q=r.childNodes[p];if(q.nodeName=="CODE"){return q}if(!(q.nodeType==3&&q.nodeValue.match(/\s+/))){break}}}function h(t,s){var p="";for(var r=0;r<t.childNodes.length;r++){if(t.childNodes[r].nodeType==3){var q=t.childNodes[r].nodeValue;if(s){q=q.replace(/\n/g,"")}p+=q}else{if(t.chi [...]
-hljs.initHighlightingOnLoad();
-</script>
-
-
-
-<style type="text/css">
-body, td {
- font-family: sans-serif;
- background-color: white;
- font-size: 13px;
-}
-
-body {
- max-width: 800px;
- margin: auto;
- padding: 1em;
- line-height: 20px;
-}
-
-tt, code, pre {
- font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
-}
-
-h1 {
- font-size:2.2em;
-}
-
-h2 {
- font-size:1.8em;
-}
-
-h3 {
- font-size:1.4em;
-}
-
-h4 {
- font-size:1.0em;
-}
-
-h5 {
- font-size:0.9em;
-}
-
-h6 {
- font-size:0.8em;
-}
-
-a:visited {
- color: rgb(50%, 0%, 50%);
-}
-
-pre, img {
- max-width: 100%;
-}
-pre {
- overflow-x: auto;
-}
-pre code {
- display: block; padding: 0.5em;
-}
-
-code {
- font-size: 92%;
- border: 1px solid #ccc;
-}
-
-code[class] {
- background-color: #F8F8F8;
-}
-
-table, td, th {
- border: none;
-}
-
-blockquote {
- color:#666666;
- margin:0;
- padding-left: 1em;
- border-left: 0.5em #EEE solid;
-}
-
-hr {
- height: 0px;
- border-bottom: none;
- border-top-width: thin;
- border-top-style: dotted;
- border-top-color: #999999;
-}
-
- at media print {
- * {
- background: transparent !important;
- color: black !important;
- filter:none !important;
- -ms-filter: none !important;
- }
-
- body {
- font-size:12pt;
- max-width:100%;
- }
-
- a, a:visited {
- text-decoration: underline;
- }
-
- hr {
- visibility: hidden;
- page-break-before: always;
- }
-
- pre, blockquote {
- padding-right: 1em;
- page-break-inside: avoid;
- }
-
- tr, img {
- page-break-inside: avoid;
- }
-
- img {
- max-width: 100% !important;
- }
-
- @page :left {
- margin: 15mm 20mm 15mm 10mm;
- }
-
- @page :right {
- margin: 15mm 10mm 15mm 20mm;
- }
-
- p, h2, h3 {
- orphans: 3; widows: 3;
- }
-
- h2, h3 {
- page-break-after: avoid;
- }
-}
-</style>
-
-<meta name="keywords" content="R, package, vignette, future, promise, lazy evaluation, synchronous, asynchronous, parallel, cluster">
-<meta name="author" content="Henrik Bengtsson">
-
-</head>
-
-<body>
-<h1>A Future for R: A Comprehensive Overview</h1>
-
-<h2>Introduction</h2>
-
-<p>The purpose of the <a href="http://cran.r-project.org/package=future">future</a> package is to provide a very simple and uniform way of evaluating R expressions asynchronously using various resources available to the user.</p>
-
-<p>In programming, a <em>future</em> is an abstraction for a <em>value</em> that may be available at some point in the future. The state of a future can either be <em>unresolved</em> or <em>resolved</em>. As soon as it is resolved, the value is available instantaneously. If the value is queried while the future is still unresolved, the current process is <em>blocked</em> until the future is resolved. It is possible to check whether a future is resolved or not without blocking. Exact [...]
-
-<p>Here is an example illustrating how the basics of futures work. First, consider the following code snippet that uses plain R code:</p>
-
-<pre><code class="r">> v <- {
-+ cat("Resolving...\n")
-+ 3.14
-+ }
-Resolving...
-> v
-[1] 3.14
-</code></pre>
-
-<p>It works by assigning the value of an expression to variable <code>v</code> and we then print the value of <code>v</code>. Moreover, when the expression for <code>v</code> is evaluated we also print a message.</p>
-
-<p>Here is the same code snippet modified to use futures instead:</p>
-
-<pre><code class="r">> library("future")
-> v %<-% {
-+ cat("Resolving...\n")
-+ 3.14
-+ }
-Resolving...
-> v
-[1] 3.14
-</code></pre>
-
-<p>The difference is in how <code>v</code> is constructed; with plain R we use <code><-</code> whereas with futures we use <code>%<-%</code>.</p>
-
-<p>So why are futures useful? Because we can choose to evaluate the future expression in a separate R process asynchronously by simply switching settings as:</p>
-
-<pre><code class="r">> library("future")
-> plan(multiprocess)
-> v %<-% {
-+ cat("Resolving...\n")
-+ 3.14
-+ }
-> v
-[1] 3.14
-</code></pre>
-
-<p>With asynchronous futures, the current/main R process does <em>not</em> block, which means it is available for further processing while the futures are being resolved
-in separates processes running in the background. In other words, futures provide a simple but yet powerful construct for parallel and / or distributed processing in R.</p>
-
-<p>Now, if you cannot be bothered to read all the nitty-gritty details about futures, but just want to try them out, then skip to the end to play with the Mandelbrot demo using both parallel and non-parallel evaluation.</p>
-
-<h2>Implicit or Explicit Futures</h2>
-
-<p>Futures can be created either <em>implicitly</em> or <em>explicitly</em>. In the introductory example above we used <em>implicit futures</em> created via the <code>v %<-% { expr }</code> construct. An alternative is <em>explicit futures</em> using the <code>f <- future({ expr })</code> and <code>v <- value(f)</code> constructs. With these, our example could alternatively be written as:</p>
-
-<pre><code class="r">> library("future")
-> f <- future({
-+ cat("Resolving...\n")
-+ 3.14
-+ })
-Resolving...
-> v <- value(f)
-> v
-[1] 3.14
-</code></pre>
-
-<p>Either style of future construct works equally(*) well. The implicit style is most similar to how regular R code is written. In principle, all you have to do is to replace <code><-</code> with a <code>%<-%</code> to turn the assignment into a future assignment. On the other hand, this simplicity can also be deceiving, particularly when asynchronous futures are being used. In contrast, the explicit style makes it much clearer that futures are being used, which lowers the risk [...]
-
-<p>(*) There are cases where <code>%<-%</code> cannot be used without some (small) modifications. We will return to this in Section 'Constraints when using Implicit Futures' near the end of this document.</p>
-
-<p>To summarize, for explicit futures, we use:</p>
-
-<ul>
-<li><code>f <- future({ expr })</code> - creates a future</li>
-<li><code>v <- value(f)</code> - gets the value of the future (blocks if not yet resolved)</li>
-</ul>
-
-<p>For implicit futures, we use:</p>
-
-<ul>
-<li><code>v %<-% { expr }</code> - creates a future and a promise to its value</li>
-</ul>
-
-<p>To keep it simple, we will use the implicit style in the rest of this document, but everything discussed will also apply to explicit futures.</p>
-
-<h2>Controlling How Futures are Resolved</h2>
-
-<p>The future package implements the following types of futures:</p>
-
-<table><thead>
-<tr>
-<th align="left">Name</th>
-<th align="left">OSes</th>
-<th align="left">Description</th>
-</tr>
-</thead><tbody>
-<tr>
-<td align="left"><em>synchronous:</em></td>
-<td align="left"></td>
-<td align="left"><em>non-parallel:</em></td>
-</tr>
-<tr>
-<td align="left"><code>eager</code></td>
-<td align="left">all</td>
-<td align="left"></td>
-</tr>
-<tr>
-<td align="left"><code>lazy</code></td>
-<td align="left">all</td>
-<td align="left">lazy evaluation - happens only if the value is requested</td>
-</tr>
-<tr>
-<td align="left"><code>transparent</code></td>
-<td align="left">all</td>
-<td align="left">for debugging (eager w/ early signaling and w/out local)</td>
-</tr>
-<tr>
-<td align="left"><em>asynchronous:</em></td>
-<td align="left"></td>
-<td align="left"><em>parallel</em>:</td>
-</tr>
-<tr>
-<td align="left"><code>multiprocess</code></td>
-<td align="left">all</td>
-<td align="left">multicore iff supported, otherwise multisession</td>
-</tr>
-<tr>
-<td align="left"><code>multisession</code></td>
-<td align="left">all</td>
-<td align="left">background R sessions (on current machine)</td>
-</tr>
-<tr>
-<td align="left"><code>multicore</code></td>
-<td align="left">not Windows</td>
-<td align="left">forked R processes (on current machine)</td>
-</tr>
-<tr>
-<td align="left"><code>cluster</code></td>
-<td align="left">all</td>
-<td align="left">external R sessions on current, local, and/or remote machines</td>
-</tr>
-<tr>
-<td align="left"><code>remote</code></td>
-<td align="left">all</td>
-<td align="left">Simple access to remote R sessions</td>
-</tr>
-</tbody></table>
-
-<p>The future package is designed such that support for additional strategies can be implemented as well. For instance, the <a href="https://github.com/HenrikBengtsson/future.BatchJobs">future.BatchJobs</a> package provides futures for all types of <em>cluster functions</em> (“backends”) that the <a href="http://cran.r-project.org/package=BatchJobs">BatchJobs</a> package supports. Specifically, futures for evaluating R expressions via job schedulers such as Slurm, TORQUE/PB [...]
-
-<p>By default, future expressions are evaluated instantaneously and synchronously (in the current R session). This evaluation strategy is referred to as “eager” and we refer to futures using this strategy as “eager futures”. In this section, we will go through each of these strategies and discuss what they have in common and how they differ.</p>
-
-<h3>Consistent Behavior Across Futures</h3>
-
-<p>Before going through each of the different future strategies, it is probably helpful to clarify the objectives the Future API (as defined by the future package). When programming with futures, it should not really matter what future strategy is used for executing code. This is because we cannot really know what computational resources the user has access to so the choice of evaluation strategy should be in the hand of the user and not the developer. In other words, the code should [...]
-
-<p>One of the designs of the Future API was to encapsulate any differences such that all types of futures will appear to work the same. This despite expressions may be evaluated locally in the current R session or across the world in remote R sessions. Another obvious advantage of having a consistent API and behavior among different types of futures is that it helps while prototyping. Typically one would use eager evaluation while building up a script and, later, when the script is fu [...]
-
-<p>Because of this, the defaults of the different strategies are such that the results and side effects of evaluating a future expression are as similar as possible. More specifically, the following is true for all futures:</p>
-
-<ul>
-<li><p>All <em>evaluation is done in a local environment</em> (i.e. <code>local({ expr })</code>) such assignments do not affect the calling environment. This is natural when evaluating in an external R process, but is also enforced when evaluating in the current R session.</p></li>
-<li><p>When a future is constructed, <em>global variables are identified</em>. For asynchronous evaluation, globals are exported to the R process/session that will be evaluating the future expression. For lazy futures, globals are “frozen” (cloned to a local environment of the future). Also, in order to protect against exporting too large objects by mistake, there is a built-in assertion that the total size of all globals is less than a given threshold (controllable via an [...]
-<li><p>Future <em>expressions are only evaluated once</em>. As soon as the value (or an error) has been collected it will be available for all succeeding requests.</p></li>
-</ul>
-
-<p>Here is an example illustrating that all assignments are done to a local environment:</p>
-
-<pre><code class="r">> plan(eager)
-> a <- 1
-> x %<-% {
-+ a <- 2
-+ 2 * a
-+ }
-> x
-[1] 4
-> a
-[1] 1
-</code></pre>
-
-<p>Now we are ready to explore the different future strategies.</p>
-
-<h3>Synchronous Futures</h3>
-
-<p>Synchronous futures are resolved one after another and most commonly by the R process that creates them. When a synchronous future is being resolved it blocks the main process until resolved. There are two main types of synchronous futures in the future package, <em>eager</em> and <em>lazy</em> futures, which are described next.</p>
-
-<h4>Eager Futures</h4>
-
-<p>Eager futures are the default unless otherwise specified. They were designed to behave as similar as possible to regular R evaluation while still fulfilling the Future API and its behaviors. Here is an example illustrating their properties:</p>
-
-<pre><code class="r">> plan(eager)
-> pid <- Sys.getpid()
-> pid
-[1] 31757
-> a %<-% {
-+ pid <- Sys.getpid()
-+ cat("Resolving 'a' ...\n")
-+ 3.14
-+ }
-Resolving 'a' ...
-> b %<-% {
-+ rm(pid)
-+ cat("Resolving 'b' ...\n")
-+ Sys.getpid()
-+ }
-Resolving 'b' ...
-> c %<-% {
-+ cat("Resolving 'c' ...\n")
-+ 2 * a
-+ }
-Resolving 'c' ...
-> b
-[1] 31757
-> c
-[1] 6.28
-> a
-[1] 3.14
-> pid
-[1] 31757
-</code></pre>
-
-<p>Since eager evaluation is taking place, each of the three futures is resolved instantaneously in the moment it is created. Note also how <code>pid</code> in the calling environment, which was assigned the process ID of the current process, is neither overwritten nor removed. This is because futures are evaluated in a local environment. Since synchronous (uni-)processing is used, future <code>b</code> is resolved by the main R process (still in a local environment), which is why the [...]
-
-<h4>Lazy Futures</h4>
-
-<p>A lazy future evaluates its expression only if its value is queried. Evaluation can also be triggered when the future is checked for being resolved or not. Here is the above example when using lazy evaluation:</p>
-
-<pre><code class="r">> plan(lazy)
-> pid <- Sys.getpid()
-> pid
-[1] 31757
-> a %<-% {
-+ pid <- Sys.getpid()
-+ cat("Resolving 'a' ...\n")
-+ 3.14
-+ }
-> b %<-% {
-+ rm(pid)
-+ cat("Resolving 'b' ...\n")
-+ Sys.getpid()
-+ }
-> c %<-% {
-+ cat("Resolving 'c' ...\n")
-+ 2 * a
-+ }
-Resolving 'a' ...
-> b
-Resolving 'b' ...
-[1] 31757
-> c
-Resolving 'c' ...
-[1] 6.28
-> a
-[1] 3.14
-> pid
-[1] 31757
-</code></pre>
-
-<p>As previously, variable <code>pid</code> is unaffected because all evaluation is done in a local environment. More interestingly, future <code>a</code> is no longer evaluated in the moment it is created, but instead when it is needed the first time, which happens when future <code>c</code> is created. This is because <code>a</code> is identified as a global variable that needs to be captured (“frozen” to <code>a == 3.14</code>) in order to set up future <code>c</code>. [...]
-
-<p><em>Comment</em>: Lazy evaluation is already used by R itself. Arguments are passed to functions using lazy evaluation. It is also possible to assign variables using lazy evaluation using <code>delayedAssign()</code>, but contrary to lazy futures this function does not freeze globals. For more information, see <code>help("delayedAssign", package="base")</code>.</p>
-
-<h3>Asynchronous Futures</h3>
-
-<p>Next, we will turn to asynchronous futures, which are futures that are resolved in the background. By design, these futures are non-blocking, that is, after being created the calling process is available for other tasks including creating additional futures. It is only when the calling process tries to access the value of a future that is not yet resolved, or trying to create another asynchronous future when all available R processes are busy serving other futures, that it blocks.</p>
-
-<h4>Multisession Futures</h4>
-
-<p>We start with multisession futures because they are supported by all operating systems. A multisession future is evaluated in a background R session running on the same machine as the calling R process. Here is our example with multisession evaluation:</p>
-
-<pre><code class="r">> plan(multisession)
-> pid <- Sys.getpid()
-> pid
-[1] 31757
-> a %<-% {
-+ pid <- Sys.getpid()
-+ cat("Resolving 'a' ...\n")
-+ 3.14
-+ }
-> b %<-% {
-+ rm(pid)
-+ cat("Resolving 'b' ...\n")
-+ Sys.getpid()
-+ }
-> c %<-% {
-+ cat("Resolving 'c' ...\n")
-+ 2 * a
-+ }
-> b
-[1] 31780
-> c
-[1] 6.28
-> a
-[1] 3.14
-> pid
-[1] 31757
-</code></pre>
-
-<p>The first thing we observe is that the values of <code>a</code>, <code>c</code> and <code>pid</code> are the same as previously. However, we notice that <code>b</code> is different from before. This is because future <code>b</code> is evaluated in a different R process and therefore it returns a different process ID. Another difference is that the messages, generated by <code>cat()</code>, are no longer displayed. This is because they are outputted to the background sessions and n [...]
-
-<p>When multisession evaluation is used, the package launches a set of R sessions in the background that will serve multisession futures by evaluating their expressions as they are created. If all background sessions are busy serving other futures, the creation of the next multisession future is <em>blocked</em> until a background session becomes available again. The total number of background processes launched is decided by the value of <code>availableCores()</code>, e.g.</p>
-
-<pre><code class="r">> availableCores()
-mc.cores+1
- 3
-</code></pre>
-
-<p>This particular result tells us that the <code>mc.cores</code> option was set such that we are allowed to use in total 3 processes including the main process. In other words, with these settings, there will be 2 background processes serving the multisession futures. The <code>availableCores()</code> is also agile to different options and system environment variables. For instance, if compute cluster schedulers are used (e.g. TORQUE/PBS and Slurm), they set specific environment vari [...]
-
-<h4>Multicore Futures</h4>
-
-<p>On operating systems where R supports <em>forking</em> of processes, which is basically all operating system except Windows, an alternative to spawning R sessions in the background is to fork the existing R process. Forking an R process is considered faster than working with a separate R session running in the background. One reason is that the overhead of exporting large globals to the background session can be greater than when forking is used.
-To use multicore futures, we specify:</p>
-
-<pre><code class="r">plan(multicore)
-</code></pre>
-
-<p>The only real different between using multicore and multisession futures is that any output written (to standard output or standard error) by a multicore process is instantaneously outputted in calling process. Other than this, the behavior of using multicore evaluation is very similar to that of using multisession evaluation.</p>
-
-<p>Just like for multisession futures, the maximum number of parallel processes running will be decided by <code>availableCores()</code>, since in both cases the evaluation is done on the local machine.</p>
-
-<h4>Multiprocess Futures</h4>
-
-<p>Sometimes we do not know whether multicore futures are supported or not, but it might still be that we would like to write platform-independent scripts or instructions that work everywhere. In such cases we can specify that we want to use “multiprocess” futures as in:</p>
-
-<pre><code class="r">plan(multiprocess)
-</code></pre>
-
-<p>A multiprocess future is not a formal class of futures by itself, but rather a convenient alias for either of the two. When this is specified, multisession evaluation will be used unless multicore evaluation is supported.</p>
-
-<h4>Cluster Futures</h4>
-
-<p>Cluster futures evaluate expressions on an ad-hoc cluster (as implemented by the parallel package). For instance, assume you have access to three nodes <code>n1</code>, <code>n2</code> and <code>n3</code>, you can then use these for asynchronous evaluation as:</p>
-
-<pre><code class="r">> plan(cluster, workers = c("n1", "n2", "n3"))
-> pid <- Sys.getpid()
-> pid
-[1] 31757
-> a %<-% {
-+ pid <- Sys.getpid()
-+ cat("Resolving 'a' ...\n")
-+ 3.14
-+ }
-> b %<-% {
-+ rm(pid)
-+ cat("Resolving 'b' ...\n")
-+ Sys.getpid()
-+ }
-> c %<-% {
-+ cat("Resolving 'c' ...\n")
-+ 2 * a
-+ }
-> b
-[1] 31802
-> c
-[1] 6.28
-> a
-[1] 3.14
-> pid
-[1] 31757
-</code></pre>
-
-<p>Just as for the other asynchronous evaluation strategies, the output from <code>cat()</code> is not displayed on the current/calling machine.</p>
-
-<p>Any types of clusters that <code>parallel::makeCluster()</code> creates can be used for cluster futures. For instance, the above cluster can be explicitly set up as:</p>
-
-<pre><code class="r">cl <- parallel::makeCluster(c("n1", "n2", "n3"))
-plan(cluster, workers=cl)
-</code></pre>
-
-<p>Also, it is considered good style to shut down the cluster when it is no longer needed, that is, calling <code>parallel::stopCluster(cl)</code>. However, it will shut itself down if the main process is terminated, which will happen in the first example where the cluster in created internally. For more information on how to set up and manage such clusters, see <code>help("makeCluster", package="parallel")</code>.</p>
-
-<p>Note that with proper firewall and router configurations (e.g. port forwarding) and with automatic authentication setup (e.g. SSH key pairs), there is nothing preventing us from using the same approach for using a cluster of remote machines.</p>
-
-<h3>Different Strategies for Different Futures</h3>
-
-<p>Sometimes one may want to use an alternative evaluation strategy for a specific future. Although one can use <code>old <- plan(new)</code> and afterward <code>plan(old)</code> to temporarily switch strategies, a simpler approach is to use the <code>%plan%</code> operator, e.g.</p>
-
-<pre><code class="r">> plan(eager)
-> pid <- Sys.getpid()
-> pid
-[1] 31757
-> a %<-% {
-+ Sys.getpid()
-+ }
-> b %<-% {
-+ Sys.getpid()
-+ } %plan% multiprocess
-> c %<-% {
-+ Sys.getpid()
-+ } %plan% multiprocess
-> a
-[1] 31757
-> b
-[1] 31819
-> c
-[1] 31820
-</code></pre>
-
-<p>As seen by the different process IDs, future <code>a</code> is evaluated eagerly using the same process as the calling environment whereas the other two are evaluated using multiprocess futures.</p>
-
-<p>However, using different plans to individual futures this way has the drawback of hard coding the evaluation strategy. Doing so may prevent some users from using your script or your package, because they do not have the sufficient resources. It may also prevent users with a lot of resources from utilizing those because you assumed a less-powerful set of hardware. Because of this, we recommend against the use of <code>%plan%</code> other than for interactive prototyping.</p>
-
-<h3>Nested Futures and Evaluation Topologies</h3>
-
-<p>This far we have discussed what can be referred to as “flat topology” of futures, that is, all futures are created in and assigned to the same environment. However, there is nothing stopping us from using a “nested topology” of futures, where one set of futures may, in turn, create another set of futures internally and so on.</p>
-
-<p>For instance, here is an example of two “top” futures (<code>a</code> and <code>b</code>) that uses multiprocess evaluation and where the second future (<code>b</code>) in turn uses two internal futures:</p>
-
-<pre><code class="r">> plan(multiprocess)
-> pid <- Sys.getpid()
-> a %<-% {
-+ cat("Resolving 'a' ...\n")
-+ Sys.getpid()
-+ }
-> b %<-% {
-+ cat("Resolving 'b' ...\n")
-+ b1 %<-% {
-+ cat("Resolving 'b1' ...\n")
-+ Sys.getpid()
-+ }
-+ b2 %<-% {
-+ cat("Resolving 'b2' ...\n")
-+ Sys.getpid()
-+ }
-+ c(b.pid = Sys.getpid(), b1.pid = b1, b2.pid = b2)
-+ }
-> pid
-[1] 31757
-> a
-[1] 31821
-> b
- b.pid b1.pid b2.pid
- 31822 31822 31822
-</code></pre>
-
-<p>By inspection the process IDs, we see that there are in total three different processes involved for resolving the futures. There is the main R process (pid 31757), and there are the two processes used by <code>a</code> (pid 31821) and <code>b</code> (pid 31822). However, the two futures (<code>b1</code> and <code>b2</code>) that is nested by <code>b</code> are evaluated by the same R process as <code>b</code>. This is because nested futures use eager evaluation unless otherwise sp [...]
-
-<p>To specify a different type of <em>evaluation topology</em>, other than the first level of futures being resolved by multiprocess evaluation and the second level by eager evaluation, we can provide a list of evaluation strategies to <code>plan()</code>. First, the same evaluation strategies as above can be explicitly specified as:</p>
-
-<pre><code class="r">plan(list(multiprocess, eager))
-</code></pre>
-
-<p>We would actually get the same behavior if we try with multiple levels of multiprocess evaluations;</p>
-
-<pre><code class="r">> plan(list(multiprocess, multiprocess))
-[...]
-> pid
-[1] 31757
-> a
-[1] 31823
-> b
- b.pid b1.pid b2.pid
- 31824 31824 31824
-</code></pre>
-
-<p>The reason for this is, also here, to protect us from launching more processes than what the machine can support. Internally, this is done by setting <code>mc.cores</code> to zero (<a href="https://github.com/HenrikBengtsson/Wishlist-for-R/issues/7">sic!</a>) such that no <em>additional</em> parallel processes can be launched. This is the case for both multisession and multicore evaluation.</p>
-
-<p>Continuing, if we start off by eager evaluation and then use multiprocess evaluation for any nested futures, we get:</p>
-
-<pre><code class="r">> plan(list(eager, multiprocess))
-[...]
-Resolving 'a' ...
-Resolving 'b' ...
-> pid
-[1] 31757
-> a
-[1] 31757
-> b
- b.pid b1.pid b2.pid
- 31757 31825 31826
-</code></pre>
-
-<p>which clearly show that <code>a</code> and <code>b</code> are resolved in the calling process (pid 31757) whereas the two nested futures (<code>b1</code> and <code>b2</code>) are resolved in two separate R processes (pids 31825 and 31826).</p>
-
-<p>Having said this, it is indeed possible to use nested multiprocess evaluation strategies, if we explicitly specify (read <em>force</em>) the number of cores available at each level. In order to do this we need to “tweak” the default settings, which can be done as follows:</p>
-
-<pre><code class="r">> plan(list(tweak(multiprocess, workers = 3), tweak(multiprocess,
-+ workers = 3)))
-[...]
-> pid
-[1] 31757
-> a
-[1] 31827
-> b
- b.pid b1.pid b2.pid
- 31828 31829 31834
-</code></pre>
-
-<p>First, we see that both <code>a</code> and <code>b</code> are resolved in different processes (pids 31827 and 31828) than the calling process (pid 31757). Second, the two nested futures (<code>b1</code> and <code>b2</code>) are resolved in yet two other R processes (pids 31829 and 31834).</p>
-
-<p>To clarify, when we set up the two levels of multiprocess evaluation, we specified that in total 3 processes may be used at each level. We choose three parallel processes, not just two, because one is always consumed by the calling process leaving two to be used for the asynchronous futures. This is why we see that <code>pid</code>, <code>a</code> and <code>b</code> are all resolved by the same process. If we had allowed only two cores at the top level, <code>a</code> and <code>b</ [...]
-
-<p>For more details on working with nested futures and different evaluation strategies at each level, see Vignette '<a href="future-3-topologies.html">Futures in R: Future Topologies</a>'.</p>
-
-<h3>Checking A Future without Blocking</h3>
-
-<p>It is possible to check whether a future has been resolved or not without blocking. This can be done using the <code>resolved(f)</code> function, which takes an explicit future <code>f</code> as input. If we work with implicit futures (as in all the examples above), we can use the <code>f <- futureOf(a)</code> function to retrieve the explicit future from an implicit one. For example,</p>
-
-<pre><code class="r">> plan(multiprocess)
-> a %<-% {
-+ cat("Resolving 'a' ...")
-+ Sys.sleep(2)
-+ cat("done\n")
-+ Sys.getpid()
-+ }
-> cat("Waiting for 'a' to be resolved ...\n")
-Waiting for 'a' to be resolved ...
-> f <- futureOf(a)
-> count <- 1
-> while (!resolved(f)) {
-+ cat(count, "\n")
-+ Sys.sleep(0.2)
-+ count <- count + 1
-+ }
-1
-2
-3
-4
-5
-> cat("Waiting for 'a' to be resolved ... DONE\n")
-Waiting for 'a' to be resolved ... DONE
-> a
-[1] 31835
-</code></pre>
-
-<h2>Failed Futures</h2>
-
-<p>Sometimes the future is not what you expected. If an error occurs while evaluating a future, the error is propagated and thrown as an error in the calling environment <em>when the future value is requested</em>. For example,</p>
-
-<pre><code class="r">> plan(lazy)
-> a %<-% {
-+ cat("Resolving 'a' ...\n")
-+ stop("Whoops!")
-+ 42
-+ }
-> cat("Everything is still ok although we have created a future that will fail.\n")
-Everything is still ok although we have created a future that will fail.
-> a
-Resolving 'a' ...
-Error in eval(expr, envir, enclos) : Whoops!
-</code></pre>
-
-<p>The error is thrown each time the value is requested, that is, if we try to get the value again will generate the same error:</p>
-
-<pre><code class="r">> a
-Error in eval(expr, envir, enclos) : Whoops!
-In addition: Warning message:
-restarting interrupted promise evaluation
-</code></pre>
-
-<p>To see the list of calls (evaluated expressions) that lead up to the error, we can use the <code>backtrace()</code> function(*) on the future, i.e.</p>
-
-<pre><code class="r">> backtrace(a)
-[[1]]
-eval(quote({
- cat("Resolving 'a' ...\n")
- stop("Whoops!")
- 42
-}), new.env())
-[[2]]
-eval(expr, envir, enclos)
-[[3]]
-stop("Whoops!")
-</code></pre>
-
-<p>(*) The commonly used <code>traceback()</code> does not provide relevant information in the context of futures.</p>
-
-<h2>Globals</h2>
-
-<p>Whenever an R expression is to be evaluated asynchronously (in parallel) or via lazy evaluation, global objects have to be identified and passed to the evaluator. They need to be passed exactly as they were at the time the future was created, because, for a lazy future, globals may otherwise change between when it is created and when it is resolved. For asynchronous processing, the reason globals need to be identified is so that they can be exported to the process that evaluates the [...]
-
-<p>The future package tries to automate these tasks as far as possible. It does this with help of the <a href="http://cran.r-project.org/package=globals">globals</a> package. If a global variable is identified, it is captured and made available to the evaluating process.
-Moreover, if a global is defined in a package, then that global is not exported. Instead, it is made sure that the corresponding package is attached when the future is evaluated. This not only better reflects the setup of the main R session, but it also minimizes the need for exporting globals, which saves not only memory but also time and bandwidth, especially when using remote compute nodes.</p>
-
-<p>Finally, it should be clarified that identifying globals from static code inspection alone is a challenging problem. There will always be corner cases where automatic identification of globals fails so that either false globals are identified (less of a concern) or some of the true globals are missing (which will result in a runtime error or possibly the wrong results). Vignette '<a href="future-2-issues.html">Futures in R: Common Issues with Solutions</a>' provides examples [...]
-
-<h2>Constraints when using Implicit Futures</h2>
-
-<p>There is one limitation with implicit futures that does not exist for explicit ones. Because an explicit future is just like any other object in R it can be assigned anywhere/to anything. For instance, we can create several of them in a loop and assign them to a list, e.g.</p>
-
-<pre><code class="r">> plan(multiprocess)
-> f <- list()
-> for (ii in 1:3) {
-+ f[[ii]] <- future({
-+ Sys.getpid()
-+ })
-+ }
-> v <- lapply(f, FUN = value)
-> str(v)
-List of 3
- $ : int 31838
- $ : int 31839
- $ : int 31840
-</code></pre>
-
-<p>This is <em>not</em> possible to do when using implicit futures. This is because the <code>%<-%</code> assignment operator <em>cannot</em> be used in all cases where the regular <code><-</code> assignment operator can be used. It can only be used to assign future values to <em>environments</em> (including the calling environment) much like how <code>assign(name, value, envir)</code> works. However, we can assign implicit futures to environments using <em>named indices</em>, e.g.</p>
-
-<pre><code class="r">> plan(multiprocess)
-> v <- new.env()
-> for (name in c("a", "b", "c")) {
-+ v[[name]] %<-% {
-+ Sys.getpid()
-+ }
-+ }
-> v <- as.list(v)
-> str(v)
-List of 3
- $ a: int 31841
- $ b: int 31842
- $ c: int 31844
-</code></pre>
-
-<p>Here <code>as.list(v)</code> blocks until all futures in the environment <code>v</code> have been resolved. Then their values are collected and returned as a regular list.</p>
-
-<p>If <em>numeric indices</em> are required, then <em>list environments</em> can be used. List environments, which are implemented by the <a href="http://cran.r-project.org/package=listenv">listenv</a> package, are regular environments with customized subsetting operators making it possible to index them much like how lists can be indexed. By using list environments where we otherwise would use lists, we can also assign implicit futures to list-like objects using numeric indices. For [...]
-
-<pre><code class="r">> library("listenv")
-> plan(multiprocess)
-> v <- listenv()
-> for (ii in 1:3) {
-+ v[[ii]] %<-% {
-+ Sys.getpid()
-+ }
-+ }
-> v <- as.list(v)
-> str(v)
-List of 3
- $ : int 31845
- $ : int 31846
- $ : int 31847
-</code></pre>
-
-<p>As previously, <code>as.list(v)</code> blocks until all futures are resolved.</p>
-
-<h2>Demos</h2>
-
-<p>To see a live illustration how different types of futures are evaluated, run the Mandelbrot demo of this package. First, try with the eager evaluation,</p>
-
-<pre><code class="r">library("future")
-plan(eager)
-demo("mandelbrot", package="future", ask=FALSE)
-</code></pre>
-
-<p>which closely imitates how the script would run if futures were not used. Then try the same using lazy evaluation,</p>
-
-<pre><code class="r">plan(lazy)
-demo("mandelbrot", package="future", ask=FALSE)
-</code></pre>
-
-<p>and see if you can notice the difference in how and when statements are evaluated.
-You may also try multiprocess evaluation, which calculates the different Mandelbrot planes using parallel R processes running in the background. Try,</p>
-
-<pre><code class="r">plan(multiprocess)
-demo("mandelbrot", package="future", ask=FALSE)
-</code></pre>
-
-<p>This will use multicore processing if you are on a system where R supports process forking, otherwise (such as on Windows) it will use multisession processing.</p>
-
-<p>Finally, if you have access to multiple machines you can try to set up a cluster of workers and use them, e.g.</p>
-
-<pre><code class="r">plan(cluster, workers=c("n2", "n5", "n6", "n6", "n9"))
-demo("mandelbrot", package="future", ask=FALSE)
-</code></pre>
-
-<h2>Contributing</h2>
-
-<p>The goal of this package is to provide a standardized and unified API for using futures in R. What you are seeing right now is an early but sincere attempt to achieve this goal. If you have comments or ideas on how to improve the 'future' package, I would love to hear about them. The preferred way to get in touch is via the <a href="https://github.com/HenrikBengtsson/future/">GitHub repository</a>, where you also find the latest source code. I am also open to contributions [...]
-
-<hr/>
-
-<p>Copyright Henrik Bengtsson, 2015-2016</p>
-
-</body>
-
-</html>
diff --git a/inst/doc/future-2-issues.html b/inst/doc/future-2-issues.html
deleted file mode 100644
index 1a2aff3..0000000
--- a/inst/doc/future-2-issues.html
+++ /dev/null
@@ -1,447 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
-
-<title>A Future for R: Common Issues with Solutions</title>
-
-<script type="text/javascript">
-window.onload = function() {
- var imgs = document.getElementsByTagName('img'), i, img;
- for (i = 0; i < imgs.length; i++) {
- img = imgs[i];
- // center an image if it is the only element of its parent
- if (img.parentElement.childElementCount === 1)
- img.parentElement.style.textAlign = 'center';
- }
-};
-</script>
-
-<!-- Styles for R syntax highlighter -->
-<style type="text/css">
- pre .operator,
- pre .paren {
- color: rgb(104, 118, 135)
- }
-
- pre .literal {
- color: #990073
- }
-
- pre .number {
- color: #099;
- }
-
- pre .comment {
- color: #998;
- font-style: italic
- }
-
- pre .keyword {
- color: #900;
- font-weight: bold
- }
-
- pre .identifier {
- color: rgb(0, 0, 0);
- }
-
- pre .string {
- color: #d14;
- }
-</style>
-
-<!-- R syntax highlighter -->
-<script type="text/javascript">
-var hljs=new function(){function m(p){return p.replace(/&/gm,"&").replace(/</gm,"<")}function f(r,q,p){return RegExp(q,"m"+(r.cI?"i":"")+(p?"g":""))}function b(r){for(var p=0;p<r.childNodes.length;p++){var q=r.childNodes[p];if(q.nodeName=="CODE"){return q}if(!(q.nodeType==3&&q.nodeValue.match(/\s+/))){break}}}function h(t,s){var p="";for(var r=0;r<t.childNodes.length;r++){if(t.childNodes[r].nodeType==3){var q=t.childNodes[r].nodeValue;if(s){q=q.replace(/\n/g,"")}p+=q}else{if(t.chi [...]
-hljs.initHighlightingOnLoad();
-</script>
-
-
-
-<style type="text/css">
-body, td {
- font-family: sans-serif;
- background-color: white;
- font-size: 13px;
-}
-
-body {
- max-width: 800px;
- margin: auto;
- padding: 1em;
- line-height: 20px;
-}
-
-tt, code, pre {
- font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
-}
-
-h1 {
- font-size:2.2em;
-}
-
-h2 {
- font-size:1.8em;
-}
-
-h3 {
- font-size:1.4em;
-}
-
-h4 {
- font-size:1.0em;
-}
-
-h5 {
- font-size:0.9em;
-}
-
-h6 {
- font-size:0.8em;
-}
-
-a:visited {
- color: rgb(50%, 0%, 50%);
-}
-
-pre, img {
- max-width: 100%;
-}
-pre {
- overflow-x: auto;
-}
-pre code {
- display: block; padding: 0.5em;
-}
-
-code {
- font-size: 92%;
- border: 1px solid #ccc;
-}
-
-code[class] {
- background-color: #F8F8F8;
-}
-
-table, td, th {
- border: none;
-}
-
-blockquote {
- color:#666666;
- margin:0;
- padding-left: 1em;
- border-left: 0.5em #EEE solid;
-}
-
-hr {
- height: 0px;
- border-bottom: none;
- border-top-width: thin;
- border-top-style: dotted;
- border-top-color: #999999;
-}
-
- at media print {
- * {
- background: transparent !important;
- color: black !important;
- filter:none !important;
- -ms-filter: none !important;
- }
-
- body {
- font-size:12pt;
- max-width:100%;
- }
-
- a, a:visited {
- text-decoration: underline;
- }
-
- hr {
- visibility: hidden;
- page-break-before: always;
- }
-
- pre, blockquote {
- padding-right: 1em;
- page-break-inside: avoid;
- }
-
- tr, img {
- page-break-inside: avoid;
- }
-
- img {
- max-width: 100% !important;
- }
-
- @page :left {
- margin: 15mm 20mm 15mm 10mm;
- }
-
- @page :right {
- margin: 15mm 10mm 15mm 20mm;
- }
-
- p, h2, h3 {
- orphans: 3; widows: 3;
- }
-
- h2, h3 {
- page-break-after: avoid;
- }
-}
-</style>
-
-<meta name="keywords" content="R, package, vignette, future, promise">
-<meta name="author" content="Henrik Bengtsson">
-
-</head>
-
-<body>
-<h1>A Future for R: Common Issues with Solutions</h1>
-
-<p>In the ideal case, all it takes to start using futures in R is to replace select standard assignments (<code><-</code>) in your R code with future assignments (<code>%<-%</code>) and make sure the right-hand side (RHS) expressions are within curly brackets (<code>{ ... }</code>). Also, if you assign these to lists (e.g. in a for loop), you need to use a list environment (<code>listenv</code>) instead of a plain list.</p>
-
-<p>However, as show below, there are few cases where you might run into some hurdles, but, as also shown, they are often easy to overcome. These are often related to global variables. </p>
-
-<p><em>If you identify other cases, please consider <a href="https://github.com/HenrikBengtsson/future/issues/">reporting</a> them so they can be documented here and possibly even be fixed.</em></p>
-
-<h2>Issues with globals</h2>
-
-<h3>Missing or incorrect globals (false negatives)</h3>
-
-<h4>Global variable obscured by subassignment</h4>
-
-<p>When a global variable is a vector, a matrix, a list, a data frame, an environment, or any other type of object that can be assigned via subsetting, the global package fails to identify it as a global variable if its first occurrence in the future expression is as part of a subsetting assignment.
-For example,</p>
-
-<pre><code class="r">> library("future")
-> plan(lazy)
-> x <- matrix(1:12, nrow=3, ncol=4)
-> y %<-% {
-+ x[1,1] <- 3
-+ 42
-+ }
-> rm(x)
-> y
-Error in x[1, 1] <- 3 : object 'x' not found
-</code></pre>
-
-<p>Another example is</p>
-
-<pre><code class="r">> library("future")
-> plan(lazy)
-> x <- list(a=1, b=2)
-> y %<-% {
-+ x$c <- 3
-+ 42
-+ }
-> rm(x)
-> y
-Error in x$c <- 3 : object 'x' not found
-</code></pre>
-
-<p>A workaround is to explicitly tell the future package about the global variable by simply listing it at the beginning of the expression, e.g.</p>
-
-<pre><code class="r">> library("future")
-> plan(lazy)
-> x <- list(a=1, b=2)
-> y %<-% {
-+ x ## Force 'x' to be global
-+ x$c <- 3
-+ 42
-+ }
-> rm(x)
-> y
-[1] 42
-</code></pre>
-
-<p><em>Comment</em>: The goal is that the <a href="https://cran.r-project.org/package=globals">globals</a> package will also handle the above case in a future version. </p>
-
-<h4>do.call() - function not found</h4>
-
-<p>When calling a function using <code>do.call()</code> make sure to specify the function as the object itself and not by name. This will help identify the function as a global object in the future expression. For instance, use</p>
-
-<pre><code class="r">do.call(file_ext, list("foo.txt"))
-</code></pre>
-
-<p>instead of</p>
-
-<pre><code class="r">do.call("file_ext", list("foo.txt"))
-</code></pre>
-
-<p>so that <code>file_ext()</code> is properly located and exported. Although you may not notice a difference when evaluating futures in the same R session, it may become a problem if you use a character string instead of a function object when futures are evaluated in external R sessions, such as on a cluster.
-It may also become a problem with lazy futures if the intended function is redefined after the future is resolved. For example,</p>
-
-<pre><code class="r">> library("future")
-> library("listenv")
-> library("tools")
-> plan(lazy)
-> pathnames <- c("foo.txt", "bar.png", "yoo.md")
-> res <- listenv()
-> for (ii in seq_along(pathnames)) {
-+ res[[ii]] %<-% do.call("file_ext", list(pathnames[ii]))
-+ }
-> file_ext <- function(...) "haha!"
-> unlist(res)
-[1] "haha!" "haha!" "haha!"
-</code></pre>
-
-<h2>Trying to pass an unresolved future to another future</h2>
-
-<p>It is not possible for a future to resolve another one unless it was created by the future trying to resolve it. For instance, the following gives an error:</p>
-
-<pre><code class="r">> library("future")
-> plan(multiprocess)
-> f1 <- future({ Sys.getpid() })
-> f2 <- future({ value(f1) })
-> v1 <- value(f1)
-[1] 7464
-> v2 <- value(f2)
-Error: Invalid usage of futures: A future whose value has not yet been collected
- can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
- 1276 on MyMachine) that created it, not by any other R processes (5579f789-e7b6
- -bace-c50d-6c7a23ddb5a3; pid 2352 on MyMachine): {; Sys.getpid(); }
-</code></pre>
-
-<p>This is because the main R process creates two futures, but then the second future tries to retrieve the value of the first one. This is an invalid request because the second future has no channel to communicate with the first future; it is only the process that created a future who can communicate with it(*).</p>
-
-<p>Note that it is only <em>unresolved</em> futures that cannot be queried this way. Thus, the solution to the above problem is to make sure all futures are resolved before they are passed to other futures, e.g.</p>
-
-<pre><code class="r">> f1 <- future({ Sys.getpid() })
-> v1 <- value(f1)
-> v1
-[1] 7464
-> f2 <- future({ value(f1) })
-> v2 <- value(f2)
-> v2
-[1] 7464
-</code></pre>
-
-<p>This works because the value has already been collected and stored inside future <code>f1</code> before future <code>f2</code> is created. Since the value is already stored internally, <code>value(f1)</code> is readily available everywhere. Of course, instead of using <code>value(f1)</code> for the second future, it would be more readable and cleaner to simply use <code>v1</code>.</p>
-
-<p>The above is typically not a problem when future assignments are used. For example:</p>
-
-<pre><code class="r">> v1 %<-% { Sys.getpid() })
-> v2 %<-% { v1 }
-> v1
-[1] 2352
-> v2
-[1] 2352
-</code></pre>
-
-<p>The reason that this approach works out of the box is because in the second future assignment <code>v1</code> is identified as a global variable, which is retrieved. Up to this point, <code>v1</code> is a promise (“delayed assignment” in R), but when it is retrieved as a global variable its value is resolved and <code>v1</code> becomes a regular variable.</p>
-
-<p>However, there are cases where future assignments can be passed via global variables without being resolved. This can happen if the future assignment is done to an element of an environment (including list environments). For instance,</p>
-
-<pre><code class="r">> library("listenv")
-> x <- listenv()
-> x$a %<-% { Sys.getpid() }
-> x$b %<-% { x$a }
-> x$a
-[1] 2352
-> x$b
-Error: Invalid usage of futures: A future whose value has not yet been collected
- can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
- 1276 on localhost) that created it, not by any other R processes (2ce86ccd-5854
- -7a05-1373-e1b20022e4d8; pid 7464 on localhost): {; Sys.getpid(); }
-</code></pre>
-
-<p>As previously, this can be avoided by making sure <code>x$a</code> is resolved first, which can be one in various ways, e.g. <code>dummy <- x$a</code>, <code>resolve(x$a)</code> and <code>force(x$a)</code>.</p>
-
-<p><em>Footnote</em>: (*) Although certain types of futures, such as eager and lazy ones, could be passed on to other futures and be resolved there because they share the same evaluation process, by definition of the Future API it is invalid to do so regardless of future type. This conservative approach is taken in order to make future expressions behave consistently regardless of the type of future used.</p>
-
-<h2>Miscellaneous</h2>
-
-<h3>Clashes with other packages</h3>
-
-<p>Sometimes other packages have functions or operators with the same name as the future package, and if those packages are attached <em>after</em> the future package, their objects will mask the ones of the future package. For instance, the igraph package also defines a <code>%<-%</code> operator which clashes with the one in future <em>if used at the prompt or in a script</em> (it is not a problem inside package because there we explicitly import objects in a known order). Here is [...]
-
-<pre><code class="r">> library("future")
-> library("igraph")
-
-Attaching package: 'igraph'
-
-The following objects are masked from 'package:future':
-
- %<-%, %->%
-
-The following objects are masked from 'package:stats':
-
- decompose, spectrum
-
-The following object is masked from 'package:base':
-
- union
-
-> y %<-% { 42 }
-Error in get(".igraph.from", parent.frame()) :
- object '.igraph.from' not found
-</code></pre>
-
-<p>Here we get an error because <code>%<-%</code> is from igraph and not the future assignment operator as we wanted. This can be confirmed as:</p>
-
-<pre><code class="r">> environment(`%<-%`)
-<environment: namespace:igraph>
-</code></pre>
-
-<p>To avoid this problem, attach the two packages in opposite order such that future comes last and thereby overrides igraph, i.e.</p>
-
-<pre><code class="r">> library("igraph")
-> library("future")
-
-Attaching package: 'future'
-
-The following objects are masked from 'package:igraph':
-
-%<-%, %->%
-
-> y %<-% { 42 }
-> y
-[1] 42
-</code></pre>
-
-<p>An alternative is to detach the future package and re-attach it, which will achieve the same thing:</p>
-
-<pre><code class="r">> detach("package:future")
-> library("future")
-</code></pre>
-
-<p>Yet another alternative is to explicitly override the object by importing it to the global environment, e.g.</p>
-
-<pre><code class="r">> `%<-%` <- future::`%<-%`
-> y %<-% { 42 }
-> y
-[1] 42
-</code></pre>
-
-<p>In this case, it does not matter in what order the packages are attached because we will always use the copy of <code>future::`%<-%`</code>.</p>
-
-<h3>Syntax error: “non-numeric argument to binary operator”</h3>
-
-<p>The future assignment operator <code>%<-%</code> is a <em>binary infix operator</em>, which means it has higher precedence than most other binary operators but also higher than some of the unary operators in R. For instance, this explains why we get the following error:</p>
-
-<pre><code class="r">> x %<-% 2 * runif(1)
-Error in x %<-% 2 * runif(1) : non-numeric argument to binary operator
-</code></pre>
-
-<p>What effectively is happening here is that because of the higher priority of <code>%<-%</code>, we first create a future <code>x %<-% 2</code> and then we try to multiply the future (not its value) with the value of <code>runif(1)</code> - which makes no sense. In order to properly assign the future variable, we need to put the future expression within curly brackets;</p>
-
-<pre><code class="r">> x %<-% { 2 * runif(1) }
-> x
-[1] 1.030209
-</code></pre>
-
-<p>Parentheses will also do. For details on precedence on operators in R, see Section 'Infix and prefix operators' in the 'R Language Definition' document.</p>
-
-<hr/>
-
-<p>Copyright Henrik Bengtsson, 2015-2016</p>
-
-</body>
-
-</html>
diff --git a/inst/doc/future-2-issues.md.rsp b/inst/doc/future-2-issues.md.rsp
deleted file mode 100644
index bd916df..0000000
--- a/inst/doc/future-2-issues.md.rsp
+++ /dev/null
@@ -1,322 +0,0 @@
-<%@meta language="R-vignette" content="--------------------------------
-%\VignetteIndexEntry{A Future for R: Common Issues with Solutions}
-%\VignetteAuthor{Henrik Bengtsson}
-%\VignetteKeyword{R}
-%\VignetteKeyword{package}
-%\VignetteKeyword{vignette}
-%\VignetteKeyword{future}
-%\VignetteKeyword{promise}
-%\VignetteEngine{R.rsp::rsp}
-%\VignetteTangle{FALSE}
---------------------------------------------------------------------"%>
-# <%@meta name="title"%>
-
-In the ideal case, all it takes to start using futures in R is to replace select standard assignments (`<-`) in your R code with future assignments (`%<-%`) and make sure the right-hand side (RHS) expressions are within curly brackets (`{ ... }`). Also, if you assign these to lists (e.g. in a for loop), you need to use a list environment (`listenv`) instead of a plain list.
-
-However, as show below, there are few cases where you might run into some hurdles, but, as also shown, they are often easy to overcome. These are often related to global variables.
-
-_If you identify other cases, please consider [reporting](https://github.com/HenrikBengtsson/future/issues/) them so they can be documented here and possibly even be fixed._
-
-
-## Issues with globals
-
-
-### Missing or incorrect globals (false negatives)
-
-#### Global variable obscured by subassignment
-When a global variable is a vector, a matrix, a list, a data frame, an environment, or any other type of object that can be assigned via subsetting, the global package fails to identify it as a global variable if its first occurrence in the future expression is as part of a subsetting assignment.
-For example,
-```r
-> library("future")
-> plan(lazy)
-> x <- matrix(1:12, nrow=3, ncol=4)
-> y %<-% {
-+ x[1,1] <- 3
-+ 42
-+ }
-> rm(x)
-> y
-Error in x[1, 1] <- 3 : object 'x' not found
-```
-Another example is
-```r
-> library("future")
-> plan(lazy)
-> x <- list(a=1, b=2)
-> y %<-% {
-+ x$c <- 3
-+ 42
-+ }
-> rm(x)
-> y
-Error in x$c <- 3 : object 'x' not found
-```
-A workaround is to explicitly tell the future package about the global variable by simply listing it at the beginning of the expression, e.g.
-```r
-> library("future")
-> plan(lazy)
-> x <- list(a=1, b=2)
-> y %<-% {
-+ x ## Force 'x' to be global
-+ x$c <- 3
-+ 42
-+ }
-> rm(x)
-> y
-[1] 42
-```
-
-_Comment_: The goal is that the [globals] package will also handle the above case in a future version.
-
-
-
-#### do.call() - function not found
-When calling a function using `do.call()` make sure to specify the function as the object itself and not by name. This will help identify the function as a global object in the future expression. For instance, use
-```r
-do.call(file_ext, list("foo.txt"))
-```
-instead of
-```r
-do.call("file_ext", list("foo.txt"))
-```
-so that `file_ext()` is properly located and exported. Although you may not notice a difference when evaluating futures in the same R session, it may become a problem if you use a character string instead of a function object when futures are evaluated in external R sessions, such as on a cluster.
-It may also become a problem with lazy futures if the intended function is redefined after the future is resolved. For example,
-```r
-> library("future")
-> library("listenv")
-> library("tools")
-> plan(lazy)
-> pathnames <- c("foo.txt", "bar.png", "yoo.md")
-> res <- listenv()
-> for (ii in seq_along(pathnames)) {
-+ res[[ii]] %<-% do.call("file_ext", list(pathnames[ii]))
-+ }
-> file_ext <- function(...) "haha!"
-> unlist(res)
-[1] "haha!" "haha!" "haha!"
-```
-
-<%---
-### False globals due to non-standard evaluation (false positives)
-
-#### subset(data, x < 3)
-
-Consider the following use of `subset()`:
-```r
-> data <- data.frame(x=1:5, y=1:5)
-> v <- subset(data, x < 3)$y
-> v
-[1] 1 2
-```
-From a static code inspection point of view, the expression `x < 3` asks for variable `x` to be compared to 3, and there is nothing specifying that `x` is part of `data` and not the global environment. That `x` is indeed part of the `data` object can only safely be inferred at runtime when `subset()` is called. This is not a problem in the above snippet, but when using futures all global/unknown variables need to be captured when the future is created (it is too late to do it when the [...]
-```r
-> library("future")
-> data <- data.frame(x=1:5, y=1:5)
-> v %<-% subset(data, x < 3)$y
-Error in globalsOf(expr, envir = envir, tweak = tweakExpression, dotdotdot = "return", :
- Identified a global by static code inspection, but failed to locate the corresponding
- object in the relevant environments: 'x'
-```
-Above, code inspection of the future expression `subset(data, x < 3)$y` incorrectly identifies `x` as a global variables that needs to be captured ("frozen") for the (lazy) future. Since no such variable `x` exists, we get an error.
-
-A clearer and backward-compatible solution to this problem is to explicitly specify the context of `x`, i.e.
-```r
-> data <- data.frame(x=1:5, y=1:5)
-> v %<-% subset(data, data$x < 3)$y
-> v
-[1] 1 2
-```
-
-An alternative is to use a dummy variable. In contrast to the code-inspection algorithm used to identify globals, _we know from reading the documentation_ that `subset()` will look for `x` in the `data` object, not in the parent environments. Armed with this knowledge, we can trick the [future] package (more precisely the [globals] package) to pick up a dummy variable `x` instead, e.g.
-```r
-> data <- data.frame(x=1:5, y=1:5)
-> x <- NULL ## To please future et al.
-> v %<-% subset(data, x < 3)$y
-> v
-[1] 1 2
-```
-
-#### ggplot2
-Another common use case for non-standard evaluation is when creating ggplot2 figures. For instance, in
-```r
-> library("ggplot2")
-> p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
-> p
-```
-fields `mpg` and `wt` of the `mtcars` data object are plotted against each other. That `mpg` and `wt` are fields of `mtcars` cannot be inferred from code inspection alone, but you need to know that that is how ggplot2 works. Analogously to the above `subset()` example, this explains why we get the following error:
-```r
-> library("future")
-> library("ggplot2")
-> p %<-% { ggplot(mtcars, aes(wt, mpg)) + geom_point() }
-Error in globalsOf(expr, envir = envir, tweak = tweakExpression, dotdotdot = "return", :
- Identified a global by static code inspection, but failed to locate the corresponding
- object in the relevant environments: 'wt'
-```
-A few comments are needed here. First of all, because `%<-%` has higher precedence than `+`, we need to place all of the ggplot2 expression within curly brackets, otherwise, we get an error. Second, the reason for only `wt` being listed as a missing global variable and not `mpg` is because the latter is (incorrectly) located to be `ggplot2::mpg`.
-
-One workaround is to make use of the `*_string()` functions of ggplot2, e.g.
-```r
-> p %<-% { ggplot(mtcars, aes_string('wt', 'mpg')) + geom_point() }
-> p
-```
-Another one, is to explicitly specify `mtcars$wt` and `mtcars$mpg`, which may become a bit tedious.
-A third alternative is to make use of dummy variables `wt` and `mpg`, i.e.
-```r
-> p %<-% {
-+ wt <- mpg <- NULL
-+ ggplot(mtcars, aes(wt, mpg)) + geom_point()
-+ }
-> p
-```
-By the way, since all futures are evaluated in a local environment, the dummy variables are _not_ assigned to the calling environment.
----%>
-
-
-## Trying to pass an unresolved future to another future
-It is not possible for a future to resolve another one unless it was created by the future trying to resolve it. For instance, the following gives an error:
-```r
-> library("future")
-> plan(multiprocess)
-> f1 <- future({ Sys.getpid() })
-> f2 <- future({ value(f1) })
-> v1 <- value(f1)
-[1] 7464
-> v2 <- value(f2)
-Error: Invalid usage of futures: A future whose value has not yet been collected
- can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
- 1276 on MyMachine) that created it, not by any other R processes (5579f789-e7b6
- -bace-c50d-6c7a23ddb5a3; pid 2352 on MyMachine): {; Sys.getpid(); }
-```
-This is because the main R process creates two futures, but then the second future tries to retrieve the value of the first one. This is an invalid request because the second future has no channel to communicate with the first future; it is only the process that created a future who can communicate with it(*).
-
-Note that it is only _unresolved_ futures that cannot be queried this way. Thus, the solution to the above problem is to make sure all futures are resolved before they are passed to other futures, e.g.
-```r
-> f1 <- future({ Sys.getpid() })
-> v1 <- value(f1)
-> v1
-[1] 7464
-> f2 <- future({ value(f1) })
-> v2 <- value(f2)
-> v2
-[1] 7464
-```
-This works because the value has already been collected and stored inside future `f1` before future `f2` is created. Since the value is already stored internally, `value(f1)` is readily available everywhere. Of course, instead of using `value(f1)` for the second future, it would be more readable and cleaner to simply use `v1`.
-
-The above is typically not a problem when future assignments are used. For example:
-```r
-> v1 %<-% { Sys.getpid() })
-> v2 %<-% { v1 }
-> v1
-[1] 2352
-> v2
-[1] 2352
-```
-The reason that this approach works out of the box is because in the second future assignment `v1` is identified as a global variable, which is retrieved. Up to this point, `v1` is a promise ("delayed assignment" in R), but when it is retrieved as a global variable its value is resolved and `v1` becomes a regular variable.
-
-However, there are cases where future assignments can be passed via global variables without being resolved. This can happen if the future assignment is done to an element of an environment (including list environments). For instance,
-```r
-> library("listenv")
-> x <- listenv()
-> x$a %<-% { Sys.getpid() }
-> x$b %<-% { x$a }
-> x$a
-[1] 2352
-> x$b
-Error: Invalid usage of futures: A future whose value has not yet been collected
- can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
- 1276 on localhost) that created it, not by any other R processes (2ce86ccd-5854
- -7a05-1373-e1b20022e4d8; pid 7464 on localhost): {; Sys.getpid(); }
-```
-As previously, this can be avoided by making sure `x$a` is resolved first, which can be one in various ways, e.g. `dummy <- x$a`, `resolve(x$a)` and `force(x$a)`.
-
-_Footnote_: (*) Although certain types of futures, such as eager and lazy ones, could be passed on to other futures and be resolved there because they share the same evaluation process, by definition of the Future API it is invalid to do so regardless of future type. This conservative approach is taken in order to make future expressions behave consistently regardless of the type of future used.
-
-
-## Miscellaneous
-
-### Clashes with other packages
-
-Sometimes other packages have functions or operators with the same name as the future package, and if those packages are attached _after_ the future package, their objects will mask the ones of the future package. For instance, the igraph package also defines a `%<-%` operator which clashes with the one in future _if used at the prompt or in a script_ (it is not a problem inside package because there we explicitly import objects in a known order). Here is what we might get:
-```r
-> library("future")
-> library("igraph")
-
-Attaching package: 'igraph'
-
-The following objects are masked from 'package:future':
-
- %<-%, %->%
-
-The following objects are masked from 'package:stats':
-
- decompose, spectrum
-
-The following object is masked from 'package:base':
-
- union
-
-> y %<-% { 42 }
-Error in get(".igraph.from", parent.frame()) :
- object '.igraph.from' not found
-```
-Here we get an error because `%<-%` is from igraph and not the future assignment operator as we wanted. This can be confirmed as:
-```r
-> environment(`%<-%`)
-<environment: namespace:igraph>
-```
-
-To avoid this problem, attach the two packages in opposite order such that future comes last and thereby overrides igraph, i.e.
-```r
-> library("igraph")
-> library("future")
-
-Attaching package: 'future'
-
-The following objects are masked from 'package:igraph':
-
-%<-%, %->%
-
-> y %<-% { 42 }
-> y
-[1] 42
-```
-
-An alternative is to detach the future package and re-attach it, which will achieve the same thing:
-```r
-> detach("package:future")
-> library("future")
-```
-
-Yet another alternative is to explicitly override the object by importing it to the global environment, e.g.
-```r
-> `%<-%` <- future::`%<-%`
-> y %<-% { 42 }
-> y
-[1] 42
-```
-In this case, it does not matter in what order the packages are attached because we will always use the copy of `` future::`%<-%` ``.
-
-
-
-### Syntax error: "non-numeric argument to binary operator"
-The future assignment operator `%<-%` is a _binary infix operator_, which means it has higher precedence than most other binary operators but also higher than some of the unary operators in R. For instance, this explains why we get the following error:
-```r
-> x %<-% 2 * runif(1)
-Error in x %<-% 2 * runif(1) : non-numeric argument to binary operator
-```
-What effectively is happening here is that because of the higher priority of `%<-%`, we first create a future `x %<-% 2` and then we try to multiply the future (not its value) with the value of `runif(1)` - which makes no sense. In order to properly assign the future variable, we need to put the future expression within curly brackets;
-```r
-> x %<-% { 2 * runif(1) }
-> x
-[1] 1.030209
-```
-Parentheses will also do. For details on precedence on operators in R, see Section 'Infix and prefix operators' in the 'R Language Definition' document.
-
-
-
-[future]: https://cran.r-project.org/package=future
-[globals]: https://cran.r-project.org/package=globals
-[listenv]: https://cran.r-project.org/package=listenv
-
----
-Copyright Henrik Bengtsson, 2015-2016
diff --git a/inst/doc/future-3-topologies.html b/inst/doc/future-3-topologies.html
deleted file mode 100644
index bca3084..0000000
--- a/inst/doc/future-3-topologies.html
+++ /dev/null
@@ -1,367 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
-
-<title>A Future for R: Future Topologies</title>
-
-<script type="text/javascript">
-window.onload = function() {
- var imgs = document.getElementsByTagName('img'), i, img;
- for (i = 0; i < imgs.length; i++) {
- img = imgs[i];
- // center an image if it is the only element of its parent
- if (img.parentElement.childElementCount === 1)
- img.parentElement.style.textAlign = 'center';
- }
-};
-</script>
-
-<!-- Styles for R syntax highlighter -->
-<style type="text/css">
- pre .operator,
- pre .paren {
- color: rgb(104, 118, 135)
- }
-
- pre .literal {
- color: #990073
- }
-
- pre .number {
- color: #099;
- }
-
- pre .comment {
- color: #998;
- font-style: italic
- }
-
- pre .keyword {
- color: #900;
- font-weight: bold
- }
-
- pre .identifier {
- color: rgb(0, 0, 0);
- }
-
- pre .string {
- color: #d14;
- }
-</style>
-
-<!-- R syntax highlighter -->
-<script type="text/javascript">
-var hljs=new function(){function m(p){return p.replace(/&/gm,"&").replace(/</gm,"<")}function f(r,q,p){return RegExp(q,"m"+(r.cI?"i":"")+(p?"g":""))}function b(r){for(var p=0;p<r.childNodes.length;p++){var q=r.childNodes[p];if(q.nodeName=="CODE"){return q}if(!(q.nodeType==3&&q.nodeValue.match(/\s+/))){break}}}function h(t,s){var p="";for(var r=0;r<t.childNodes.length;r++){if(t.childNodes[r].nodeType==3){var q=t.childNodes[r].nodeValue;if(s){q=q.replace(/\n/g,"")}p+=q}else{if(t.chi [...]
-hljs.initHighlightingOnLoad();
-</script>
-
-
-
-<style type="text/css">
-body, td {
- font-family: sans-serif;
- background-color: white;
- font-size: 13px;
-}
-
-body {
- max-width: 800px;
- margin: auto;
- padding: 1em;
- line-height: 20px;
-}
-
-tt, code, pre {
- font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
-}
-
-h1 {
- font-size:2.2em;
-}
-
-h2 {
- font-size:1.8em;
-}
-
-h3 {
- font-size:1.4em;
-}
-
-h4 {
- font-size:1.0em;
-}
-
-h5 {
- font-size:0.9em;
-}
-
-h6 {
- font-size:0.8em;
-}
-
-a:visited {
- color: rgb(50%, 0%, 50%);
-}
-
-pre, img {
- max-width: 100%;
-}
-pre {
- overflow-x: auto;
-}
-pre code {
- display: block; padding: 0.5em;
-}
-
-code {
- font-size: 92%;
- border: 1px solid #ccc;
-}
-
-code[class] {
- background-color: #F8F8F8;
-}
-
-table, td, th {
- border: none;
-}
-
-blockquote {
- color:#666666;
- margin:0;
- padding-left: 1em;
- border-left: 0.5em #EEE solid;
-}
-
-hr {
- height: 0px;
- border-bottom: none;
- border-top-width: thin;
- border-top-style: dotted;
- border-top-color: #999999;
-}
-
- at media print {
- * {
- background: transparent !important;
- color: black !important;
- filter:none !important;
- -ms-filter: none !important;
- }
-
- body {
- font-size:12pt;
- max-width:100%;
- }
-
- a, a:visited {
- text-decoration: underline;
- }
-
- hr {
- visibility: hidden;
- page-break-before: always;
- }
-
- pre, blockquote {
- padding-right: 1em;
- page-break-inside: avoid;
- }
-
- tr, img {
- page-break-inside: avoid;
- }
-
- img {
- max-width: 100% !important;
- }
-
- @page :left {
- margin: 15mm 20mm 15mm 10mm;
- }
-
- @page :right {
- margin: 15mm 10mm 15mm 20mm;
- }
-
- p, h2, h3 {
- orphans: 3; widows: 3;
- }
-
- h2, h3 {
- page-break-after: avoid;
- }
-}
-</style>
-
-<meta name="keywords" content="R, package, vignette, future, promise">
-<meta name="author" content="Henrik Bengtsson">
-
-</head>
-
-<body>
-<h1>A Future for R: Future Topologies</h1>
-
-<p>Futures can be nested in R such that one future creates another set of futures and so on. This may, for instance, occur within nested for loops, e.g.</p>
-
-<pre><code class="r">library("future")
-library("listenv")
-x <- listenv()
-for (ii in 1:3) {
- x[[ii]] %<-% {
- y <- listenv()
- for (jj in 1:3) {
- y[[jj]] %<-% { ii + jj/10 }
- }
- y
- }
-}
-unlist(x)
-## [1] 1.1 1.2 1.3 2.1 2.2 2.3 3.1 3.2 3.3
-</code></pre>
-
-<p>The default is to use eager futures unless otherwise specified, which is also true for nested futures. If we for instance specify, <code>plan(multiprocess)</code>, the first layer of futures (<code>x[[ii]] %<-% { expr }</code>) will be processed asynchronously in background R processes, and the futures in the second layer of futures (<code>y[[jj]] %<-% { expr }</code>) will be processed synchronously in the current R processes (one of the background processes). If we wish to u [...]
-
-<h2>Example: High-Throughput Sequencing</h2>
-
-<p>Consider a high-throughput sequencing (HT-Seq) project with 50 human DNA samples where we have one FASTQ file per sample containing the raw sequence reads as they come out of the sequencing machine. With this data, we wish to align each FASTQ to a reference genome such that we generate 24 individual BAM files per sample - one per chromosome.</p>
-
-<p>Here is the layout of what such an analysis could look like in R using futures.</p>
-
-<pre><code class="r">library("future")
-library("listenv")
-htseq_align <- function(fq, chr) { chr }
-
-fqs <- dir(pattern="[.]fastq$")
-
-bams <- listenv()
-for (ss in seq_along(fqs)) {
- fq <- fqs[ss]
- bams[[ss]] %<-% {
- bams_ss <- listenv()
- for (cc in 1:24) {
- bams_ss[[cc]] %<-% htseq_align(fq, chr=cc)
- }
- as.list(bams_ss)
- }
-}
-bams <- as.list(bams)
-</code></pre>
-
-<p>The default is to use eager futures, so without further specifications, the above will process each sample and each chromosome sequentially. Next, we will consider what can be done with the following two computer setups:</p>
-
-<ul>
-<li>A single machine with 8 cores</li>
-<li>A compute cluster with 3 machines each with 16 cores</li>
-</ul>
-
-<h3>One multi-core machine</h3>
-
-<p>With a single machine of 8 cores, we could choose to process multiple samples at the same while processing chromosomes sequentially. In other words, we would like to evaluate the outer layer of futures using multiprocess futures and the inner ones as regular (uniprocess) eager futures. This can be specified as:</p>
-
-<pre><code class="r">plan(list(multiprocess, eager))
-</code></pre>
-
-<p>The internals for processing multiprocess future queries <code>availableCores()</code> to infer how many cores can be used simultaneously, so there is no need to explicitly specify that there are 8 cores available.</p>
-
-<p><em>Comment</em>: Since eager is the default future, we could skip trailing eager futures in the setup, e.g. <code>plan(list(multiprocess))</code> or just <code>plan(multiprocess)</code>. However, it does hurt to be explicit.</p>
-
-<p>If we instead would like to process the sample sequentially and the chromosomes in parallel, we can use:</p>
-
-<pre><code class="r">plan(list(eager, multiprocess))
-</code></pre>
-
-<p>We could also process the data such that we allocate two cores for processing two samples in parallel each using four cores for processing four chromosomes in parallel:</p>
-
-<pre><code class="r">plan(list(tweak(multiprocess, workers=2), tweak(multiprocess, workers=4)))
-</code></pre>
-
-<h3>An ad-hoc compute cluster</h3>
-
-<p>With a compute cluster of 3 machines each with 16 cores, we can run up to 48 alignment processes in parallel. A natural setup is to have one machine process one sample in parallel. We could specify this as:</p>
-
-<pre><code class="r">nodes <- c("n1", "n2", "n3")
-plan(list(tweak(cluster, workers=nodes), multiprocess))
-</code></pre>
-
-<p><em>Comment:</em> Multiprocess futures are agile to its environment, that is, they will query the machine they are running on to find out how many parallel processes it can run at the same time.</p>
-
-<p>One possible downside to the above setup is that we might not utilize all available cores all the time. This is because the alignment of the shorter chromosomes will finish sooner than the longer ones, which means that we might at the end of each sample have only a few alignment processes running on each machine leaving the remaining cores idle/unused. An alternative set up is then to use the following setup:</p>
-
-<pre><code class="r">nodes <- rep(c("n1", "n2", "n3"), each=8)
-plan(list(tweak(cluster, workers=nodes), multiprocess))
-</code></pre>
-
-<p>This will cause up to 24 (=3*8) samples to be processed in parallel each processing two chromosomes at the same time.</p>
-
-<h2>Example: A remote compute cluster</h2>
-
-<p>Imagine we have access to a remote compute cluster, with login node <code>remote.server.org</code>, and that the cluster has three nodes <code>n1</code>, <code>n2</code>, and <code>n3</code>. Also, let us assume we have already set up the cluster such that we can log in via public key authentication via SSH, i.e. when we do <code>ssh remote.server.org</code> authentication is done automatically.</p>
-
-<p>With the above setup, we can use nested futures in our local R session to evaluate R expression on the remote compute cluster and its three nodes. Here is a proof of concept illustrating how the different nested futures are evaluated on different machines.</p>
-
-<pre><code class="r">library("future")
-library("listenv")
-
-## Set up access to remote login node
-login <- tweak(remote, workers="remote.server.org")
-plan(login)
-
-## Set up cluster nodes on login node
-nodes %<-% { .keepme <- parallel::makeCluster(c("n1", "n2", "n3")) }
-
-## Specify future topology
-## login node -> { cluster nodes } -> { multiple cores }
-plan(list(
- login,
- tweak(cluster, workers=nodes),
- multiprocess
-))
-
-
-## (a) This will be evaluated on the cluster login computer
-x %<-% {
- thost <- Sys.info()[["nodename"]]
- tpid <- Sys.getpid()
- y <- listenv()
- for (task in 1:4) {
- ## (b) This will be evaluated on a compute node on the cluster
- y[[task]] %<-% {
- mhost <- Sys.info()[["nodename"]]
- mpid <- Sys.getpid()
- z <- listenv()
- for (jj in 1:2) {
- ## (c) These will be evaluated in separate processes on the same compute node
- z[[jj]] %<-% data.frame(task=task, top.host=thost, top.pid=tpid,
- mid.host=mhost, mid.pid=mpid,
- host=Sys.info()[["nodename"]], pid=Sys.getpid())
- }
- Reduce(rbind, z)
- }
- }
- Reduce(rbind, y)
-}
-
-print(x)
-## task top.host top.pid mid.host mid.pid host pid
-## 1 1 login 391547 n1 391878 n1 393943
-## 2 1 login 391547 n1 391878 n1 393951
-## 3 2 login 391547 n2 392204 n2 393971
-## 4 2 login 391547 n2 392204 n2 393978
-## 5 3 login 391547 n3 392527 n3 394040
-## 6 3 login 391547 n3 392527 n3 394048
-## 7 4 login 391547 n1 391878 n1 393959
-## 8 4 login 391547 n1 391878 n1 393966
-</code></pre>
-
-<p>Try the above <code>x %<-% { ... }</code> future with, say, <code>plan(list(lazy, multiprocess))</code> or <code>plan(list(eager, lazy, multiprocess))</code> and see what the output will be.</p>
-
-<hr/>
-
-<p>Copyright Henrik Bengtsson, 2015-2016</p>
-
-</body>
-
-</html>
diff --git a/inst/doc/future-3-topologies.md.rsp b/inst/doc/future-3-topologies.md.rsp
deleted file mode 100644
index 7b1ba5c..0000000
--- a/inst/doc/future-3-topologies.md.rsp
+++ /dev/null
@@ -1,174 +0,0 @@
-<%@meta language="R-vignette" content="--------------------------------
-%\VignetteIndexEntry{A Future for R: Future Topologies}
-%\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"%>
-
-Futures can be nested in R such that one future creates another set of futures and so on. This may, for instance, occur within nested for loops, e.g.
-```r
-library("future")
-library("listenv")
-x <- listenv()
-for (ii in 1:3) {
- x[[ii]] %<-% {
- y <- listenv()
- for (jj in 1:3) {
- y[[jj]] %<-% { ii + jj/10 }
- }
- y
- }
-}
-unlist(x)
-## [1] 1.1 1.2 1.3 2.1 2.2 2.3 3.1 3.2 3.3
-```
-The default is to use eager futures unless otherwise specified, which is also true for nested futures. If we for instance specify, `plan(multiprocess)`, the first layer of futures (`x[[ii]] %<-% { expr }`) will be processed asynchronously in background R processes, and the futures in the second layer of futures (`y[[jj]] %<-% { expr }`) will be processed synchronously in the current R processes (one of the background processes). If we wish to use a different strategy for the second lay [...]
-
-
-## Example: High-Throughput Sequencing
-Consider a high-throughput sequencing (HT-Seq) project with 50 human DNA samples where we have one FASTQ file per sample containing the raw sequence reads as they come out of the sequencing machine. With this data, we wish to align each FASTQ to a reference genome such that we generate 24 individual BAM files per sample - one per chromosome.
-
-Here is the layout of what such an analysis could look like in R using futures.
-```r
-library("future")
-library("listenv")
-htseq_align <- function(fq, chr) { chr }
-
-fqs <- dir(pattern="[.]fastq$")
-
-bams <- listenv()
-for (ss in seq_along(fqs)) {
- fq <- fqs[ss]
- bams[[ss]] %<-% {
- bams_ss <- listenv()
- for (cc in 1:24) {
- bams_ss[[cc]] %<-% htseq_align(fq, chr=cc)
- }
- as.list(bams_ss)
- }
-}
-bams <- as.list(bams)
-```
-
-The default is to use eager futures, so without further specifications, the above will process each sample and each chromosome sequentially. Next, we will consider what can be done with the following two computer setups:
-
-* A single machine with 8 cores
-* A compute cluster with 3 machines each with 16 cores
-
-### One multi-core machine
-With a single machine of 8 cores, we could choose to process multiple samples at the same while processing chromosomes sequentially. In other words, we would like to evaluate the outer layer of futures using multiprocess futures and the inner ones as regular (uniprocess) eager futures. This can be specified as:
-```r
-plan(list(multiprocess, eager))
-```
-The internals for processing multiprocess future queries `availableCores()` to infer how many cores can be used simultaneously, so there is no need to explicitly specify that there are 8 cores available.
-
-_Comment_: Since eager is the default future, we could skip trailing eager futures in the setup, e.g. `plan(list(multiprocess))` or just `plan(multiprocess)`. However, it does hurt to be explicit.
-
-If we instead would like to process the sample sequentially and the chromosomes in parallel, we can use:
-```r
-plan(list(eager, multiprocess))
-```
-
-We could also process the data such that we allocate two cores for processing two samples in parallel each using four cores for processing four chromosomes in parallel:
-```r
-plan(list(tweak(multiprocess, workers=2), tweak(multiprocess, workers=4)))
-```
-
-
-### An ad-hoc compute cluster
-With a compute cluster of 3 machines each with 16 cores, we can run up to 48 alignment processes in parallel. A natural setup is to have one machine process one sample in parallel. We could specify this as:
-```r
-nodes <- c("n1", "n2", "n3")
-plan(list(tweak(cluster, workers=nodes), multiprocess))
-```
-_Comment:_ Multiprocess futures are agile to its environment, that is, they will query the machine they are running on to find out how many parallel processes it can run at the same time.
-
-One possible downside to the above setup is that we might not utilize all available cores all the time. This is because the alignment of the shorter chromosomes will finish sooner than the longer ones, which means that we might at the end of each sample have only a few alignment processes running on each machine leaving the remaining cores idle/unused. An alternative set up is then to use the following setup:
-```r
-nodes <- rep(c("n1", "n2", "n3"), each=8)
-plan(list(tweak(cluster, workers=nodes), multiprocess))
-```
-This will cause up to 24 (=3*8) samples to be processed in parallel each processing two chromosomes at the same time.
-
-
-## Example: A remote compute cluster
-Imagine we have access to a remote compute cluster, with login node `remote.server.org`, and that the cluster has three nodes `n1`, `n2`, and `n3`. Also, let us assume we have already set up the cluster such that we can log in via public key authentication via SSH, i.e. when we do `ssh remote.server.org` authentication is done automatically.
-
-With the above setup, we can use nested futures in our local R session to evaluate R expression on the remote compute cluster and its three nodes. Here is a proof of concept illustrating how the different nested futures are evaluated on different machines.
-
-```r
-library("future")
-library("listenv")
-
-## Set up access to remote login node
-login <- tweak(remote, workers="remote.server.org")
-plan(login)
-
-## Set up cluster nodes on login node
-nodes %<-% { .keepme <- parallel::makeCluster(c("n1", "n2", "n3")) }
-
-## Specify future topology
-## login node -> { cluster nodes } -> { multiple cores }
-plan(list(
- login,
- tweak(cluster, workers=nodes),
- multiprocess
-))
-
-
-## (a) This will be evaluated on the cluster login computer
-x %<-% {
- thost <- Sys.info()[["nodename"]]
- tpid <- Sys.getpid()
- y <- listenv()
- for (task in 1:4) {
- ## (b) This will be evaluated on a compute node on the cluster
- y[[task]] %<-% {
- mhost <- Sys.info()[["nodename"]]
- mpid <- Sys.getpid()
- z <- listenv()
- for (jj in 1:2) {
- ## (c) These will be evaluated in separate processes on the same compute node
- z[[jj]] %<-% data.frame(task=task, top.host=thost, top.pid=tpid,
- mid.host=mhost, mid.pid=mpid,
- host=Sys.info()[["nodename"]], pid=Sys.getpid())
- }
- Reduce(rbind, z)
- }
- }
- Reduce(rbind, y)
-}
-
-print(x)
-## task top.host top.pid mid.host mid.pid host pid
-## 1 1 login 391547 n1 391878 n1 393943
-## 2 1 login 391547 n1 391878 n1 393951
-## 3 2 login 391547 n2 392204 n2 393971
-## 4 2 login 391547 n2 392204 n2 393978
-## 5 3 login 391547 n3 392527 n3 394040
-## 6 3 login 391547 n3 392527 n3 394048
-## 7 4 login 391547 n1 391878 n1 393959
-## 8 4 login 391547 n1 391878 n1 393966
-```
-
-Try the above `x %<-% { ... }` future with, say, `plan(list(lazy, multiprocess))` or `plan(list(eager, lazy, multiprocess))` and see what the output will be.
-
-
-[listenv]: http://cran.r-project.org/package=listenv
-[globals]: http://cran.r-project.org/package=globals
-[Futures in R: Common issues with solutions]: future-issues.html
-
----
-Copyright Henrik Bengtsson, 2015-2016
diff --git a/inst/vignettes-static/future-1-overview.md.rsp.rsp b/inst/vignettes-static/future-1-overview.md.rsp.rsp
new file mode 100644
index 0000000..e1be024
--- /dev/null
+++ b/inst/vignettes-static/future-1-overview.md.rsp.rsp
@@ -0,0 +1,683 @@
+<%---------------------------------------------------------------------
+ This *.md.rsp.rsp file is used to generate the *.md.rsp that
+ is the copied to vignettes/. The latter contains no dynamic
+ code. The reason for this is that this RSP file uses
+ multisession futures and for some unknown reason those gives
+ errors during R CMD build on Windows. Everywhere else they
+ work including when building this RSP manually. /HB 2016-04-12
+ ---------------------------------------------------------------------%>
+<%%@meta language="R-vignette" content="--------------------------------
+%\VignetteIndexEntry{A Future for R: A Comprehensive Overview}
+%\VignetteAuthor{Henrik Bengtsson}
+%\VignetteKeyword{R}
+%\VignetteKeyword{package}
+%\VignetteKeyword{vignette}
+%\VignetteKeyword{future}
+%\VignetteKeyword{promise}
+%\VignetteKeyword{lazy evaluation}
+%\VignetteKeyword{synchronous}
+%\VignetteKeyword{asynchronous}
+%\VignetteKeyword{parallel}
+%\VignetteKeyword{cluster}
+%\VignetteEngine{R.rsp::rsp}
+%\VignetteTangle{FALSE}
+
+Do not edit the *.md.rsp file. Instead edit the *.md.rsp.rsp (sic!)
+file found under inst/vignettes-static/ of the source package.
+--------------------------------------------------------------------"%%>
+<%@meta language="R-vignette" content="--------------------------------
+%\VignetteIndexEntry{A Future for R: A Comprehensive Overview}
+%\VignetteAuthor{Henrik Bengtsson}
+%\VignetteKeyword{R}
+%\VignetteKeyword{package}
+%\VignetteKeyword{vignette}
+%\VignetteKeyword{future}
+%\VignetteKeyword{promise}
+%\VignetteKeyword{lazy evaluation}
+%\VignetteKeyword{synchronous}
+%\VignetteKeyword{asynchronous}
+%\VignetteKeyword{parallel}
+%\VignetteKeyword{cluster}
+%\VignetteEngine{R.rsp::rsp}
+%\VignetteTangle{FALSE}
+--------------------------------------------------------------------"%>
+<%
+R.utils::use("R.utils")
+use("future")
+`%<-%` <- future::`%<-%`
+options("withCapture/newline"=FALSE)
+options(mc.cores=2L)
+%>
+# <%@meta name="title"%>
+
+## Introduction
+The purpose of the [future] package is to provide a very simple and uniform way of evaluating R expressions asynchronously using various resources available to the user.
+
+In programming, a _future_ is an abstraction for a _value_ that may be available at some point in the future. The state of a future can either be _unresolved_ or _resolved_. As soon as it is resolved, the value is available instantaneously. If the value is queried while the future is still unresolved, the current process is _blocked_ until the future is resolved. It is possible to check whether a future is resolved or not without blocking. Exactly how and when futures are resolved d [...]
+
+Here is an example illustrating how the basics of futures work. First, consider the following code snippet that uses plain R code:
+```r
+> v <- {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+It works by assigning the value of an expression to variable `v` and we then print the value of `v`. Moreover, when the expression for `v` is evaluated we also print a message.
+
+Here is the same code snippet modified to use futures instead:
+```r
+> library("future")
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+The difference is in how `v` is constructed; with plain R we use `<-` whereas with futures we use `%<-%`.
+
+So why are futures useful? Because we can choose to evaluate the future expression in a separate R process asynchronously by simply switching settings as:
+```r
+> library("future")
+> plan(multiprocess)
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+> v
+[1] 3.14
+```
+With asynchronous futures, the current/main R process does _not_ block, which means it is available for further processing while the futures are being resolved
+in separates processes running in the background. In other words, futures provide a simple but yet powerful construct for parallel and / or distributed processing in R.
+
+
+Now, if you cannot be bothered to read all the nitty-gritty details about futures, but just want to try them out, then skip to the end to play with the Mandelbrot demo using both parallel and non-parallel evaluation.
+
+
+
+## Implicit or Explicit Futures
+
+Futures can be created either _implicitly_ or _explicitly_. In the introductory example above we used _implicit futures_ created via the `v %<-% { expr }` construct. An alternative is _explicit futures_ using the `f <- future({ expr })` and `v <- value(f)` constructs. With these, our example could alternatively be written as:
+```r
+> library("future")
+> f <- future({
++ cat("Resolving...\n")
++ 3.14
++ })
+Resolving...
+> v <- value(f)
+> v
+[1] 3.14
+```
+
+Either style of future construct works equally(*) well. The implicit style is most similar to how regular R code is written. In principle, all you have to do is to replace `<-` with a `%<-%` to turn the assignment into a future assignment. On the other hand, this simplicity can also be deceiving, particularly when asynchronous futures are being used. In contrast, the explicit style makes it much clearer that futures are being used, which lowers the risk for mistakes and better commun [...]
+
+(*) There are cases where `%<-%` cannot be used without some (small) modifications. We will return to this in Section 'Constraints when using Implicit Futures' near the end of this document.
+
+
+
+To summarize, for explicit futures, we use:
+
+* `f <- future({ expr })` - creates a future
+* `v <- value(f)` - gets the value of the future (blocks if not yet resolved)
+
+For implicit futures, we use:
+
+* `v %<-% { expr }` - creates a future and a promise to its value
+
+To keep it simple, we will use the implicit style in the rest of this document, but everything discussed will also apply to explicit futures.
+
+
+
+## Controlling How Futures are Resolved
+The future package implements the following types of futures:
+
+| Name | OSes | Description
+|:----------------|:------------|:-----------------------------------------------------
+| _synchronous:_ | | _non-parallel:_
+| `eager` | all |
+| `lazy` | all | lazy evaluation - happens only if the value is requested
+| `transparent` | all | for debugging (eager w/ early signaling and w/out local)
+| _asynchronous:_ | | _parallel_:
+| `multiprocess` | all | multicore iff supported, otherwise multisession
+| `multisession` | all | background R sessions (on current machine)
+| `multicore` | not Windows | forked R processes (on current machine)
+| `cluster` | all | external R sessions on current, local, and/or remote machines
+| `remote` | all | Simple access to remote R sessions
+
+The future package is designed such that support for additional strategies can be implemented as well. For instance, the [future.BatchJobs] package provides futures for all types of _cluster functions_ ("backends") that the [BatchJobs] package supports. Specifically, futures for evaluating R expressions via job schedulers such as Slurm, TORQUE/PBS, Oracle/Sun Grid Engine (SGE) and Load Sharing Facility (LSF) are also available.
+
+By default, future expressions are evaluated instantaneously and synchronously (in the current R session). This evaluation strategy is referred to as "eager" and we refer to futures using this strategy as "eager futures". In this section, we will go through each of these strategies and discuss what they have in common and how they differ.
+
+
+### Consistent Behavior Across Futures
+Before going through each of the different future strategies, it is probably helpful to clarify the objectives the Future API (as defined by the future package). When programming with futures, it should not really matter what future strategy is used for executing code. This is because we cannot really know what computational resources the user has access to so the choice of evaluation strategy should be in the hand of the user and not the developer. In other words, the code should not [...]
+
+One of the designs of the Future API was to encapsulate any differences such that all types of futures will appear to work the same. This despite expressions may be evaluated locally in the current R session or across the world in remote R sessions. Another obvious advantage of having a consistent API and behavior among different types of futures is that it helps while prototyping. Typically one would use eager evaluation while building up a script and, later, when the script is fully [...]
+
+Because of this, the defaults of the different strategies are such that the results and side effects of evaluating a future expression are as similar as possible. More specifically, the following is true for all futures:
+
+* All _evaluation is done in a local environment_ (i.e. `local({ expr })`) such assignments do not affect the calling environment. This is natural when evaluating in an external R process, but is also enforced when evaluating in the current R session.
+
+* When a future is constructed, _global variables are identified_. For asynchronous evaluation, globals are exported to the R process/session that will be evaluating the future expression. For lazy futures, globals are "frozen" (cloned to a local environment of the future). Also, in order to protect against exporting too large objects by mistake, there is a built-in assertion that the total size of all globals is less than a given threshold (controllable via an option, cf. `help("futu [...]
+
+* Future _expressions are only evaluated once_. As soon as the value (or an error) has been collected it will be available for all succeeding requests.
+
+Here is an example illustrating that all assignments are done to a local environment:
+```r
+<%=withCapture({
+plan(eager)
+a <- 1
+x %<-% {
+ a <- 2
+ 2 * a
+}
+x
+a
+})%>
+```
+
+<%---
+And here is an example illustrating that globals are validated already when the future is created:
+```r
+> rm(b)
+> x %<-% { 2 * b }
+Error in globalsOf(expr, envir = envir, substitute = FALSE, tweak = tweak, :
+ Identified a global object via static code inspection ({; 2 * b; }), but
+failed to locate the corresponding object in the relevant environments: 'b'
+```
+We will return to global variables and global functions in Section 'Globals' near the end of this document.
+---%>
+
+Now we are ready to explore the different future strategies.
+
+
+### Synchronous Futures
+
+Synchronous futures are resolved one after another and most commonly by the R process that creates them. When a synchronous future is being resolved it blocks the main process until resolved. There are two main types of synchronous futures in the future package, _eager_ and _lazy_ futures, which are described next.
+
+
+#### Eager Futures
+Eager futures are the default unless otherwise specified. They were designed to behave as similar as possible to regular R evaluation while still fulfilling the Future API and its behaviors. Here is an example illustrating their properties:
+```r
+<%=withCapture({
+plan(eager)
+<%@include file="incl/future-1-overview-example2.R"%>
+})%>
+```
+Since eager evaluation is taking place, each of the three futures is resolved instantaneously in the moment it is created. Note also how `pid` in the calling environment, which was assigned the process ID of the current process, is neither overwritten nor removed. This is because futures are evaluated in a local environment. Since synchronous (uni-)processing is used, future `b` is resolved by the main R process (still in a local environment), which is why the value of `b` and `pid` a [...]
+<%
+## Sanity checks
+stopifnot(b == pid)
+%>
+
+
+#### Lazy Futures
+A lazy future evaluates its expression only if its value is queried. Evaluation can also be triggered when the future is checked for being resolved or not. Here is the above example when using lazy evaluation:
+```r
+<%=withCapture({
+plan(lazy)
+<%@include file="incl/future-1-overview-example2.R"%>
+})%>
+```
+As previously, variable `pid` is unaffected because all evaluation is done in a local environment. More interestingly, future `a` is no longer evaluated in the moment it is created, but instead when it is needed the first time, which happens when future `c` is created. This is because `a` is identified as a global variable that needs to be captured ("frozen" to `a == 3.14`) in order to set up future `c`. Later when `c` (the value of future `c`) is queried, `a` has already been resolve [...]
+
+_Comment_: Lazy evaluation is already used by R itself. Arguments are passed to functions using lazy evaluation. It is also possible to assign variables using lazy evaluation using `delayedAssign()`, but contrary to lazy futures this function does not freeze globals. For more information, see `help("delayedAssign", package="base")`.
+
+<%
+## Sanity checks
+stopifnot(b == pid)
+%>
+
+
+<%---
+#### Transparent Futures
+
+For troubleshooting, there is also a _transparent_ future, which can be specified as `plan(transparent)`. A transparent future is technically an eager future with instant signaling of conditions (including errors and warnings) and where evaluation, and therefore also assignments, take place in the calling environment. Transparent futures are particularly useful for troubleshooting errors.
+
+---%>
+
+
+
+
+### Asynchronous Futures
+Next, we will turn to asynchronous futures, which are futures that are resolved in the background. By design, these futures are non-blocking, that is, after being created the calling process is available for other tasks including creating additional futures. It is only when the calling process tries to access the value of a future that is not yet resolved, or trying to create another asynchronous future when all available R processes are busy serving other futures, that it blocks.
+
+
+#### Multisession Futures
+We start with multisession futures because they are supported by all operating systems. A multisession future is evaluated in a background R session running on the same machine as the calling R process. Here is our example with multisession evaluation:
+```r
+<%=bfr <- withCapture({
+plan(multisession)
+<%@include file="incl/future-1-overview-example2.R"%>
+})%>
+```
+The first thing we observe is that the values of `a`, `c` and `pid` are the same as previously. However, we notice that `b` is different from before. This is because future `b` is evaluated in a different R process and therefore it returns a different process ID. Another difference is that the messages, generated by `cat()`, are no longer displayed. This is because they are outputted to the background sessions and not the calling session.
+
+<%
+## Sanity checks
+if (availableCores() == 1L) {
+ stopifnot(b == pid)
+} else {
+ stopifnot(b != pid)
+}
+%>
+
+When multisession evaluation is used, the package launches a set of R sessions in the background that will serve multisession futures by evaluating their expressions as they are created. If all background sessions are busy serving other futures, the creation of the next multisession future is _blocked_ until a background session becomes available again. The total number of background processes launched is decided by the value of `availableCores()`, e.g.
+```r
+<%=withCapture({
+availableCores()
+})%>
+```
+This particular result tells us that the `mc.cores` option was set such that we are allowed to use in total <%= availableCores() %> processes including the main process. In other words, with these settings, there will be <%= availableCores()-1 %> background processes serving the multisession futures. The `availableCores()` is also agile to different options and system environment variables. For instance, if compute cluster schedulers are used (e.g. TORQUE/PBS and Slurm), they set spec [...]
+
+
+#### Multicore Futures
+On operating systems where R supports _forking_ of processes, which is basically all operating system except Windows, an alternative to spawning R sessions in the background is to fork the existing R process. Forking an R process is considered faster than working with a separate R session running in the background. One reason is that the overhead of exporting large globals to the background session can be greater than when forking is used.
+To use multicore futures, we specify:
+```r
+plan(multicore)
+```
+<%---
+```r
+<%=if (supportsMulticore()) {
+withCapture({
+plan(multicore)
+<%@include file="incl/future-1-overview-example2.R"%>
+})
+} else {
+## If this vignette is compiled on a system not supporting
+## multicore processing, let's fake the future based on
+## the output of the multisession example
+bfr <- gsub("multisession", "multicore", bfr)
+bfr <- gsub(b, b+5L, bfr)
+bfr
+}%>
+```
+---%>
+The only real different between using multicore and multisession futures is that any output written (to standard output or standard error) by a multicore process is instantaneously outputted in calling process. Other than this, the behavior of using multicore evaluation is very similar to that of using multisession evaluation.
+
+Just like for multisession futures, the maximum number of parallel processes running will be decided by `availableCores()`, since in both cases the evaluation is done on the local machine.
+
+
+
+#### Multiprocess Futures
+Sometimes we do not know whether multicore futures are supported or not, but it might still be that we would like to write platform-independent scripts or instructions that work everywhere. In such cases we can specify that we want to use "multiprocess" futures as in:
+```r
+plan(multiprocess)
+```
+A multiprocess future is not a formal class of futures by itself, but rather a convenient alias for either of the two. When this is specified, multisession evaluation will be used unless multicore evaluation is supported.
+
+
+#### Cluster Futures
+Cluster futures evaluate expressions on an ad-hoc cluster (as implemented by the parallel package). For instance, assume you have access to three nodes `n1`, `n2` and `n3`, you can then use these for asynchronous evaluation as:
+```r
+<%=
+## For the vignette we cannot assume nodes n1, n2 and n3 exist.
+## The second best we can do is to use the local machine.
+hosts <- c("localhost", "localhost", "localhost")
+bfr <- withCapture({
+plan(cluster, workers=hosts)
+<%@include file="incl/future-1-overview-example2.R"%>
+})
+bfr <- gsub('hosts', 'c("n1", "n2", "n3")', bfr)
+bfr
+%>
+```
+Just as for the other asynchronous evaluation strategies, the output from `cat()` is not displayed on the current/calling machine.
+
+<%
+## Sanity checks
+stopifnot(b != pid)
+%>
+
+Any types of clusters that `parallel::makeCluster()` creates can be used for cluster futures. For instance, the above cluster can be explicitly set up as:
+```r
+cl <- parallel::makeCluster(c("n1", "n2", "n3"))
+plan(cluster, workers=cl)
+```
+Also, it is considered good style to shut down the cluster when it is no longer needed, that is, calling `parallel::stopCluster(cl)`. However, it will shut itself down if the main process is terminated, which will happen in the first example where the cluster in created internally. For more information on how to set up and manage such clusters, see `help("makeCluster", package="parallel")`.
+
+Note that with proper firewall and router configurations (e.g. port forwarding) and with automatic authentication setup (e.g. SSH key pairs), there is nothing preventing us from using the same approach for using a cluster of remote machines.
+
+
+
+### Different Strategies for Different Futures
+Sometimes one may want to use an alternative evaluation strategy for a specific future. Although one can use `old <- plan(new)` and afterward `plan(old)` to temporarily switch strategies, a simpler approach is to use the `%plan%` operator, e.g.
+```r
+<%=withCapture({
+plan(eager)
+pid <- Sys.getpid()
+pid
+a %<-% { Sys.getpid() }
+b %<-% { Sys.getpid() } %plan% multiprocess
+c %<-% { Sys.getpid() } %plan% multiprocess
+a
+b
+c
+})%>
+```
+As seen by the different process IDs, future `a` is evaluated eagerly using the same process as the calling environment whereas the other two are evaluated using multiprocess futures.
+
+<%
+## Sanity checks
+stopifnot(a == pid)
+if (availableCores() == 1L) {
+ stopifnot(b == pid, c == pid, c == b)
+} else if (availableCores() == 2L && !supportsMulticore()) {
+ stopifnot(b != pid, c != pid, c == b)
+} else {
+ stopifnot(b != pid, c != pid, c != b)
+}
+%>
+
+
+
+However, using different plans to individual futures this way has the drawback of hard coding the evaluation strategy. Doing so may prevent some users from using your script or your package, because they do not have the sufficient resources. It may also prevent users with a lot of resources from utilizing those because you assumed a less-powerful set of hardware. Because of this, we recommend against the use of `%plan%` other than for interactive prototyping.
+
+
+### Nested Futures and Evaluation Topologies
+This far we have discussed what can be referred to as "flat topology" of futures, that is, all futures are created in and assigned to the same environment. However, there is nothing stopping us from using a "nested topology" of futures, where one set of futures may, in turn, create another set of futures internally and so on.
+
+For instance, here is an example of two "top" futures (`a` and `b`) that uses multiprocess evaluation and where the second future (`b`) in turn uses two internal futures:
+```r
+<%=withCapture({
+plan(multiprocess)
+<%@include file="incl/future-1-overview-example3.R"%>
+pid
+a
+b
+})%>
+```
+By inspection the process IDs, we see that there are in total three different processes involved for resolving the futures. There is the main R process (pid <%= pid %>), and there are the two processes used by `a` (pid <%= a %>) and `b` (pid <%= b[1] %>). However, the two futures (`b1` and `b2`) that is nested by `b` are evaluated by the same R process as `b`. This is because nested futures use eager evaluation unless otherwise specified. There are a few reasons for this, but the mai [...]
+
+<%
+## Sanity checks
+if (availableCores() == 1L) {
+ stopifnot(a == pid, all(b == pid))
+} else if (availableCores() == 2L && !supportsMulticore()) {
+ stopifnot(a != pid, all(b != pid), !all(b != a), all(b == b[1]))
+} else {
+ stopifnot(a != pid, all(b != pid), all(b != a), all(b == b[1]))
+}
+%>
+
+
+To specify a different type of _evaluation topology_, other than the first level of futures being resolved by multiprocess evaluation and the second level by eager evaluation, we can provide a list of evaluation strategies to `plan()`. First, the same evaluation strategies as above can be explicitly specified as:
+```r
+plan(list(multiprocess, eager))
+```
+We would actually get the same behavior if we try with multiple levels of multiprocess evaluations;
+```r
+<%=withCapture({
+plan(list(multiprocess, multiprocess))
+})%>
+[...]
+<%
+<%@include file="incl/future-1-overview-example3.R"%>
+%>
+<%=withCapture({
+pid
+a
+b
+})%>
+```
+The reason for this is, also here, to protect us from launching more processes than what the machine can support. Internally, this is done by setting `mc.cores` to zero ([sic!](https://github.com/HenrikBengtsson/Wishlist-for-R/issues/7)) such that no _additional_ parallel processes can be launched. This is the case for both multisession and multicore evaluation.
+
+<%
+## Sanity checks
+if (availableCores() == 1L) {
+ stopifnot(a == pid, all(b == pid))
+} else if (availableCores() == 2L && !supportsMulticore()) {
+ stopifnot(a != pid, all(b != pid), !all(b != a), all(b == b[1]))
+} else {
+ stopifnot(a != pid, all(b != pid), all(b != a), all(b == b[1]))
+}
+%>
+
+Continuing, if we start off by eager evaluation and then use multiprocess evaluation for any nested futures, we get:
+```r
+<%=withCapture({
+plan(list(eager, multiprocess))
+})%>
+[...]
+<%
+<%@include file="incl/future-1-overview-example3.R"%>
+%>
+<%=withCapture({
+pid
+a
+b
+})%>
+```
+which clearly show that `a` and `b` are resolved in the calling process (pid <%= pid %>) whereas the two nested futures (`b1` and `b2`) are resolved in two separate R processes (pids <%= b[2] %> and <%= b[3] %>).
+
+<%
+## Sanity checks
+stopifnot(a == pid, b[1] == pid)
+if (availableCores() == 1L) {
+ stopifnot(all(b == b[1]))
+} else if (availableCores() == 2L && !supportsMulticore()) {
+ stopifnot(all(b[-1] != b[1]), b[2] == b[3])
+} else {
+ stopifnot(all(b[-1] != b[1]), b[2] != b[3])
+}
+%>
+
+
+Having said this, it is indeed possible to use nested multiprocess evaluation strategies, if we explicitly specify (read _force_) the number of cores available at each level. In order to do this we need to "tweak" the default settings, which can be done as follows:
+```r
+<%=withCapture({
+plan(list(
+ tweak(multiprocess, workers=3L),
+ tweak(multiprocess, workers=3L)
+))
+})%>
+[...]
+<%
+<%@include file="incl/future-1-overview-example3.R"%>
+%>
+<%=withCapture({
+pid
+a
+b
+})%>
+```
+First, we see that both `a` and `b` are resolved in different processes (pids <%= a %> and <%= b[1] %>) than the calling process (pid <%= pid %>). Second, the two nested futures (`b1` and `b2`) are resolved in yet two other R processes (pids <%= b[2] %> and <%= b[3] %>).
+
+<%
+## Sanity checks
+stopifnot(a != pid, b[1] != pid)
+if (supportsMulticore()) {
+} else {
+ stopifnot(b[2] != b[1], b[3] != b[1])
+}
+%>
+
+To clarify, when we set up the two levels of multiprocess evaluation, we specified that in total 3 processes may be used at each level. We choose three parallel processes, not just two, because one is always consumed by the calling process leaving two to be used for the asynchronous futures. This is why we see that `pid`, `a` and `b` are all resolved by the same process. If we had allowed only two cores at the top level, `a` and `b` would have been resolved by the same background proc [...]
+
+For more details on working with nested futures and different evaluation strategies at each level, see Vignette '[Futures in R: Future Topologies]'.
+
+
+### Checking A Future without Blocking
+It is possible to check whether a future has been resolved or not without blocking. This can be done using the `resolved(f)` function, which takes an explicit future `f` as input. If we work with implicit futures (as in all the examples above), we can use the `f <- futureOf(a)` function to retrieve the explicit future from an implicit one. For example,
+```r
+<%=withCapture({
+plan(multiprocess)
+a %<-% {
+ cat("Resolving 'a' ...")
+ Sys.sleep(2)
+ cat("done\n")
+ Sys.getpid()
+}
+
+cat("Waiting for 'a' to be resolved ...\n")
+f <- futureOf(a)
+count <- 1
+while(!resolved(f)) {
+ cat(count, "\n")
+ Sys.sleep(0.2)
+ count <- count + 1
+}
+cat("Waiting for 'a' to be resolved ... DONE\n")
+
+a
+})%>
+```
+
+
+## Failed Futures
+Sometimes the future is not what you expected. If an error occurs while evaluating a future, the error is propagated and thrown as an error in the calling environment _when the future value is requested_. For example,
+```r
+<%=withCapture({
+plan(lazy)
+a %<-% {
+ cat("Resolving 'a' ...\n")
+ stop("Whoops!")
+ 42
+}
+cat("Everything is still ok although we have created a future that will fail.\n")
+})%>
+<% captureOutput(try(resolve(a), silent=TRUE)) %>
+> a
+Resolving 'a' ...
+Error in eval(expr, envir, enclos) : Whoops!
+```
+The error is thrown each time the value is requested, that is, if we try to get the value again will generate the same error:
+```r
+> a
+Error in eval(expr, envir, enclos) : Whoops!
+In addition: Warning message:
+restarting interrupted promise evaluation
+```
+To see the list of calls (evaluated expressions) that lead up to the error, we can use the `backtrace()` function(*) on the future, i.e.
+```r
+<%=withCapture({
+backtrace(a)
+})%>
+```
+(*) The commonly used `traceback()` does not provide relevant information in the context of futures.
+
+
+## Globals
+Whenever an R expression is to be evaluated asynchronously (in parallel) or via lazy evaluation, global objects have to be identified and passed to the evaluator. They need to be passed exactly as they were at the time the future was created, because, for a lazy future, globals may otherwise change between when it is created and when it is resolved. For asynchronous processing, the reason globals need to be identified is so that they can be exported to the process that evaluates the future.
+
+The future package tries to automate these tasks as far as possible. It does this with help of the [globals] package. If a global variable is identified, it is captured and made available to the evaluating process.
+<%---
+If it identifies a symbol that it believes is a global object, but it fails to locate it in the calling environment (or any the environment accessible from that one), an error is thrown immediately. This minimizing the risk for runtime errors occurring later (sometimes much later) and in a different process (possible in a remote R session), which otherwise may be hard to troubleshoot. For instance,
+```r
+> rm(a)
+> x <- 5.0
+> y %<-% { a * x }
+Error in globalsOf(expr, envir = envir, substitute = FALSE, tweak = tweak, :
+ Identified a global object via static code inspection ({; a * x; }), but
+failed to locate the corresponding object in the relevant environments: 'a'
+
+> a <- 1.8
+> y %<-% { a * x }
+> y
+[1] 9
+```
+---%>
+Moreover, if a global is defined in a package, then that global is not exported. Instead, it is made sure that the corresponding package is attached when the future is evaluated. This not only better reflects the setup of the main R session, but it also minimizes the need for exporting globals, which saves not only memory but also time and bandwidth, especially when using remote compute nodes.
+<%---
+As mentioned previously, for consistency across evaluation strategies, all types of futures validate globals upon creation. This is also true for cases where it would not be necessary, e.g. for eager evaluation of multicore evaluation (which forks the calling process "as-is"). However, in order to make it as easy as possible to switch between strategies without being surprised by slightly different behaviors, the Future API is designed to check for globals the same way regardless of strategy.
+---%>
+<%---
+Having said this, it is possible to disable validation of globals by setting `globals=FALSE`. This could make sense if one know for sure that only eager or multicore futures will be used. This argument can be tweaked as `plan(tweak(eager, globals=FALSE))` and `plan(tweak(multicore, globals=FALSE))`. However, it is strongly advised not to do this. Instead, as a best practice, it is always good if the code/script works with any type of futures.
+---%>
+
+Finally, it should be clarified that identifying globals from static code inspection alone is a challenging problem. There will always be corner cases where automatic identification of globals fails so that either false globals are identified (less of a concern) or some of the true globals are missing (which will result in a runtime error or possibly the wrong results). Vignette '[Futures in R: Common Issues with Solutions]' provides examples of common cases and explains how to avoid t [...]
+
+
+
+## Constraints when using Implicit Futures
+
+There is one limitation with implicit futures that does not exist for explicit ones. Because an explicit future is just like any other object in R it can be assigned anywhere/to anything. For instance, we can create several of them in a loop and assign them to a list, e.g.
+```r
+<%=withCapture({
+plan(multiprocess)
+f <- list()
+for (ii in 1:3) {
+ f[[ii]] <- future({ Sys.getpid() })
+}
+v <- lapply(f, FUN=value)
+str(v)
+})%>
+```
+This is _not_ possible to do when using implicit futures. This is because the `%<-%` assignment operator _cannot_ be used in all cases where the regular `<-` assignment operator can be used. It can only be used to assign future values to _environments_ (including the calling environment) much like how `assign(name, value, envir)` works. However, we can assign implicit futures to environments using _named indices_, e.g.
+```r
+<%=withCapture({
+plan(multiprocess)
+v <- new.env()
+for (name in c("a", "b", "c")) {
+ v[[name]] %<-% { Sys.getpid() }
+}
+v <- as.list(v)
+str(v)
+})%>
+```
+Here `as.list(v)` blocks until all futures in the environment `v` have been resolved. Then their values are collected and returned as a regular list.
+
+If _numeric indices_ are required, then _list environments_ can be used. List environments, which are implemented by the [listenv] package, are regular environments with customized subsetting operators making it possible to index them much like how lists can be indexed. By using list environments where we otherwise would use lists, we can also assign implicit futures to list-like objects using numeric indices. For example,
+```r
+<%=withCapture({
+library("listenv")
+plan(multiprocess)
+v <- listenv()
+for (ii in 1:3) {
+ v[[ii]] %<-% { Sys.getpid() }
+}
+v <- as.list(v)
+str(v)
+})%>
+```
+As previously, `as.list(v)` blocks until all futures are resolved.
+
+
+
+## Demos
+To see a live illustration how different types of futures are evaluated, run the Mandelbrot demo of this package. First, try with the eager evaluation,
+```r
+library("future")
+plan(eager)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+which closely imitates how the script would run if futures were not used. Then try the same using lazy evaluation,
+```r
+plan(lazy)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+and see if you can notice the difference in how and when statements are evaluated.
+You may also try multiprocess evaluation, which calculates the different Mandelbrot planes using parallel R processes running in the background. Try,
+```r
+plan(multiprocess)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+This will use multicore processing if you are on a system where R supports process forking, otherwise (such as on Windows) it will use multisession processing.
+
+Finally, if you have access to multiple machines you can try to set up a cluster of workers and use them, e.g.
+```r
+plan(cluster, workers=c("n2", "n5", "n6", "n6", "n9"))
+demo("mandelbrot", package="future", ask=FALSE)
+```
+
+
+
+## Contributing
+The goal of this package is to provide a standardized and unified API for using futures in R. What you are seeing right now is an early but sincere attempt to achieve this goal. If you have comments or ideas on how to improve the 'future' package, I would love to hear about them. The preferred way to get in touch is via the [GitHub repository](https://github.com/HenrikBengtsson/future/), where you also find the latest source code. I am also open to contributions and collaborations of [...]
+
+
+[BatchJobs]: http://cran.r-project.org/package=BatchJobs
+[future]: http://cran.r-project.org/package=future
+[future.BatchJobs]: http://cran.r-project.org/package=future.BatchJobs
+[globals]: http://cran.r-project.org/package=globals
+[listenv]: http://cran.r-project.org/package=listenv
+[Futures in R: Common Issues with Solutions]: future-2-issues.html
+[Futures in R: Future Topologies]: future-3-topologies.html
+---
+Copyright Henrik Bengtsson, 2015-2016
diff --git a/man/eager.Rd b/man/eager.Rd
index e0efefd..ba20cf0 100644
--- a/man/eager.Rd
+++ b/man/eager.Rd
@@ -66,7 +66,7 @@ plan(eager)
## A global variable
a <- 0
-## Create eager future (implicitly)
+## Create eager future (explicitly)
f <- future({
b <- 3
c <- 2
diff --git a/man/lazy.Rd b/man/lazy.Rd
index 48e709a..6ad09ed 100644
--- a/man/lazy.Rd
+++ b/man/lazy.Rd
@@ -55,7 +55,7 @@ plan(lazy)
## A global variable
a <- 0
-## Create lazy future (implicitly)
+## Create lazy future (explicitly)
f <- future({
b <- 3
c <- 2
diff --git a/tests/cluster.R b/tests/cluster.R
index 8419d12..f06521d 100644
--- a/tests/cluster.R
+++ b/tests/cluster.R
@@ -11,7 +11,7 @@ for (cores in 1:2) {
message(sprintf("Testing with %d cores ...", cores))
options(mc.cores=cores-1L)
- ## Set up a cluster with 4 nodes (explicitly)
+ ## Set up a cluster with <cores> nodes (explicitly)
cl <- parallel::makeCluster(cores)
plan(cluster, workers=cl)
@@ -28,7 +28,7 @@ for (cores in 1:2) {
stopifnot(y == 42L)
- ## Set up a cluster with 4 nodes (implicitly)
+ ## Set up a cluster with <cores> nodes (implicitly)
plan(cluster, workers=cores)
## No global variables
diff --git a/tests/globals,tricky.R b/tests/globals,tricky.R
index df39a88..f7c96fd 100644
--- a/tests/globals,tricky.R
+++ b/tests/globals,tricky.R
@@ -83,6 +83,15 @@ for (cores in 1:min(3L, availableCores())) {
rm(list="a")
message(sprintf("value(b)=%g", value(b)))
stopifnot(value(b) == 2)
+
+ ## BUG FIX: In future (<= 1.0.0) a global 'pkg' would be
+ ## overwritten by the name of the last package attached
+ ## by the future.
+ pkg <- "foo"
+ f <- eager({ pkg })
+ v <- value(f)
+ message(sprintf("value(f)=%s", sQuote(v)))
+ stopifnot(pkg == "foo", v == "foo")
} ## for (strategy ...)
message(sprintf("Method for identifying globals: '%s' ... DONE", method))
diff --git a/vignettes/future-1-overview.md.rsp b/vignettes/future-1-overview.md.rsp
new file mode 100644
index 0000000..ef864c8
--- /dev/null
+++ b/vignettes/future-1-overview.md.rsp
@@ -0,0 +1,652 @@
+<%@meta language="R-vignette" content="--------------------------------
+%\VignetteIndexEntry{A Future for R: A Comprehensive Overview}
+%\VignetteAuthor{Henrik Bengtsson}
+%\VignetteKeyword{R}
+%\VignetteKeyword{package}
+%\VignetteKeyword{vignette}
+%\VignetteKeyword{future}
+%\VignetteKeyword{promise}
+%\VignetteKeyword{lazy evaluation}
+%\VignetteKeyword{synchronous}
+%\VignetteKeyword{asynchronous}
+%\VignetteKeyword{parallel}
+%\VignetteKeyword{cluster}
+%\VignetteEngine{R.rsp::rsp}
+%\VignetteTangle{FALSE}
+
+Do not edit the *.md.rsp file. Instead edit the *.md.rsp.rsp (sic!)
+file found under inst/vignettes-static/ of the source package.
+--------------------------------------------------------------------"%>
+# A Future for R: A Comprehensive Overview
+
+## Introduction
+The purpose of the [future] package is to provide a very simple and uniform way of evaluating R expressions asynchronously using various resources available to the user.
+
+In programming, a _future_ is an abstraction for a _value_ that may be available at some point in the future. The state of a future can either be _unresolved_ or _resolved_. As soon as it is resolved, the value is available instantaneously. If the value is queried while the future is still unresolved, the current process is _blocked_ until the future is resolved. It is possible to check whether a future is resolved or not without blocking. Exactly how and when futures are resolved d [...]
+
+Here is an example illustrating how the basics of futures work. First, consider the following code snippet that uses plain R code:
+```r
+> v <- {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+It works by assigning the value of an expression to variable `v` and we then print the value of `v`. Moreover, when the expression for `v` is evaluated we also print a message.
+
+Here is the same code snippet modified to use futures instead:
+```r
+> library("future")
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+Resolving...
+> v
+[1] 3.14
+```
+The difference is in how `v` is constructed; with plain R we use `<-` whereas with futures we use `%<-%`.
+
+So why are futures useful? Because we can choose to evaluate the future expression in a separate R process asynchronously by simply switching settings as:
+```r
+> library("future")
+> plan(multiprocess)
+> v %<-% {
++ cat("Resolving...\n")
++ 3.14
++ }
+> v
+[1] 3.14
+```
+With asynchronous futures, the current/main R process does _not_ block, which means it is available for further processing while the futures are being resolved
+in separates processes running in the background. In other words, futures provide a simple but yet powerful construct for parallel and / or distributed processing in R.
+
+
+Now, if you cannot be bothered to read all the nitty-gritty details about futures, but just want to try them out, then skip to the end to play with the Mandelbrot demo using both parallel and non-parallel evaluation.
+
+
+
+## Implicit or Explicit Futures
+
+Futures can be created either _implicitly_ or _explicitly_. In the introductory example above we used _implicit futures_ created via the `v %<-% { expr }` construct. An alternative is _explicit futures_ using the `f <- future({ expr })` and `v <- value(f)` constructs. With these, our example could alternatively be written as:
+```r
+> library("future")
+> f <- future({
++ cat("Resolving...\n")
++ 3.14
++ })
+Resolving...
+> v <- value(f)
+> v
+[1] 3.14
+```
+
+Either style of future construct works equally(*) well. The implicit style is most similar to how regular R code is written. In principle, all you have to do is to replace `<-` with a `%<-%` to turn the assignment into a future assignment. On the other hand, this simplicity can also be deceiving, particularly when asynchronous futures are being used. In contrast, the explicit style makes it much clearer that futures are being used, which lowers the risk for mistakes and better commun [...]
+
+(*) There are cases where `%<-%` cannot be used without some (small) modifications. We will return to this in Section 'Constraints when using Implicit Futures' near the end of this document.
+
+
+
+To summarize, for explicit futures, we use:
+
+* `f <- future({ expr })` - creates a future
+* `v <- value(f)` - gets the value of the future (blocks if not yet resolved)
+
+For implicit futures, we use:
+
+* `v %<-% { expr }` - creates a future and a promise to its value
+
+To keep it simple, we will use the implicit style in the rest of this document, but everything discussed will also apply to explicit futures.
+
+
+
+## Controlling How Futures are Resolved
+The future package implements the following types of futures:
+
+| Name | OSes | Description
+|:----------------|:------------|:-----------------------------------------------------
+| _synchronous:_ | | _non-parallel:_
+| `eager` | all |
+| `lazy` | all | lazy evaluation - happens only if the value is requested
+| `transparent` | all | for debugging (eager w/ early signaling and w/out local)
+| _asynchronous:_ | | _parallel_:
+| `multiprocess` | all | multicore iff supported, otherwise multisession
+| `multisession` | all | background R sessions (on current machine)
+| `multicore` | not Windows | forked R processes (on current machine)
+| `cluster` | all | external R sessions on current, local, and/or remote machines
+| `remote` | all | Simple access to remote R sessions
+
+The future package is designed such that support for additional strategies can be implemented as well. For instance, the [future.BatchJobs] package provides futures for all types of _cluster functions_ ("backends") that the [BatchJobs] package supports. Specifically, futures for evaluating R expressions via job schedulers such as Slurm, TORQUE/PBS, Oracle/Sun Grid Engine (SGE) and Load Sharing Facility (LSF) are also available.
+
+By default, future expressions are evaluated instantaneously and synchronously (in the current R session). This evaluation strategy is referred to as "eager" and we refer to futures using this strategy as "eager futures". In this section, we will go through each of these strategies and discuss what they have in common and how they differ.
+
+
+### Consistent Behavior Across Futures
+Before going through each of the different future strategies, it is probably helpful to clarify the objectives the Future API (as defined by the future package). When programming with futures, it should not really matter what future strategy is used for executing code. This is because we cannot really know what computational resources the user has access to so the choice of evaluation strategy should be in the hand of the user and not the developer. In other words, the code should not [...]
+
+One of the designs of the Future API was to encapsulate any differences such that all types of futures will appear to work the same. This despite expressions may be evaluated locally in the current R session or across the world in remote R sessions. Another obvious advantage of having a consistent API and behavior among different types of futures is that it helps while prototyping. Typically one would use eager evaluation while building up a script and, later, when the script is fully [...]
+
+Because of this, the defaults of the different strategies are such that the results and side effects of evaluating a future expression are as similar as possible. More specifically, the following is true for all futures:
+
+* All _evaluation is done in a local environment_ (i.e. `local({ expr })`) such assignments do not affect the calling environment. This is natural when evaluating in an external R process, but is also enforced when evaluating in the current R session.
+
+* When a future is constructed, _global variables are identified_. For asynchronous evaluation, globals are exported to the R process/session that will be evaluating the future expression. For lazy futures, globals are "frozen" (cloned to a local environment of the future). Also, in order to protect against exporting too large objects by mistake, there is a built-in assertion that the total size of all globals is less than a given threshold (controllable via an option, cf. `help("futu [...]
+
+* Future _expressions are only evaluated once_. As soon as the value (or an error) has been collected it will be available for all succeeding requests.
+
+Here is an example illustrating that all assignments are done to a local environment:
+```r
+> plan(eager)
+> a <- 1
+> x %<-% {
++ a <- 2
++ 2 * a
++ }
+> x
+[1] 4
+> a
+[1] 1
+```
+
+
+Now we are ready to explore the different future strategies.
+
+
+### Synchronous Futures
+
+Synchronous futures are resolved one after another and most commonly by the R process that creates them. When a synchronous future is being resolved it blocks the main process until resolved. There are two main types of synchronous futures in the future package, _eager_ and _lazy_ futures, which are described next.
+
+
+#### Eager Futures
+Eager futures are the default unless otherwise specified. They were designed to behave as similar as possible to regular R evaluation while still fulfilling the Future API and its behaviors. Here is an example illustrating their properties:
+```r
+> plan(eager)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+Resolving 'a' ...
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+Resolving 'b' ...
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+Resolving 'c' ...
+> b
+[1] 28072
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+Since eager evaluation is taking place, each of the three futures is resolved instantaneously in the moment it is created. Note also how `pid` in the calling environment, which was assigned the process ID of the current process, is neither overwritten nor removed. This is because futures are evaluated in a local environment. Since synchronous (uni-)processing is used, future `b` is resolved by the main R process (still in a local environment), which is why the value of `b` and `pid` a [...]
+
+
+#### Lazy Futures
+A lazy future evaluates its expression only if its value is queried. Evaluation can also be triggered when the future is checked for being resolved or not. Here is the above example when using lazy evaluation:
+```r
+> plan(lazy)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+Resolving 'a' ...
+> b
+Resolving 'b' ...
+[1] 28072
+> c
+Resolving 'c' ...
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+As previously, variable `pid` is unaffected because all evaluation is done in a local environment. More interestingly, future `a` is no longer evaluated in the moment it is created, but instead when it is needed the first time, which happens when future `c` is created. This is because `a` is identified as a global variable that needs to be captured ("frozen" to `a == 3.14`) in order to set up future `c`. Later when `c` (the value of future `c`) is queried, `a` has already been resolve [...]
+
+_Comment_: Lazy evaluation is already used by R itself. Arguments are passed to functions using lazy evaluation. It is also possible to assign variables using lazy evaluation using `delayedAssign()`, but contrary to lazy futures this function does not freeze globals. For more information, see `help("delayedAssign", package="base")`.
+
+
+
+
+
+
+
+### Asynchronous Futures
+Next, we will turn to asynchronous futures, which are futures that are resolved in the background. By design, these futures are non-blocking, that is, after being created the calling process is available for other tasks including creating additional futures. It is only when the calling process tries to access the value of a future that is not yet resolved, or trying to create another asynchronous future when all available R processes are busy serving other futures, that it blocks.
+
+
+#### Multisession Futures
+We start with multisession futures because they are supported by all operating systems. A multisession future is evaluated in a background R session running on the same machine as the calling R process. Here is our example with multisession evaluation:
+```r
+> plan(multisession)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+> b
+[1] 28093
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+The first thing we observe is that the values of `a`, `c` and `pid` are the same as previously. However, we notice that `b` is different from before. This is because future `b` is evaluated in a different R process and therefore it returns a different process ID. Another difference is that the messages, generated by `cat()`, are no longer displayed. This is because they are outputted to the background sessions and not the calling session.
+
+
+When multisession evaluation is used, the package launches a set of R sessions in the background that will serve multisession futures by evaluating their expressions as they are created. If all background sessions are busy serving other futures, the creation of the next multisession future is _blocked_ until a background session becomes available again. The total number of background processes launched is decided by the value of `availableCores()`, e.g.
+```r
+> availableCores()
+mc.cores+1
+ 3
+```
+This particular result tells us that the `mc.cores` option was set such that we are allowed to use in total 3 processes including the main process. In other words, with these settings, there will be 2 background processes serving the multisession futures. The `availableCores()` is also agile to different options and system environment variables. For instance, if compute cluster schedulers are used (e.g. TORQUE/PBS and Slurm), they set specific environment variable specifying the numbe [...]
+
+
+#### Multicore Futures
+On operating systems where R supports _forking_ of processes, which is basically all operating system except Windows, an alternative to spawning R sessions in the background is to fork the existing R process. Forking an R process is considered faster than working with a separate R session running in the background. One reason is that the overhead of exporting large globals to the background session can be greater than when forking is used.
+To use multicore futures, we specify:
+```r
+plan(multicore)
+```
+The only real different between using multicore and multisession futures is that any output written (to standard output or standard error) by a multicore process is instantaneously outputted in calling process. Other than this, the behavior of using multicore evaluation is very similar to that of using multisession evaluation.
+
+Just like for multisession futures, the maximum number of parallel processes running will be decided by `availableCores()`, since in both cases the evaluation is done on the local machine.
+
+
+
+#### Multiprocess Futures
+Sometimes we do not know whether multicore futures are supported or not, but it might still be that we would like to write platform-independent scripts or instructions that work everywhere. In such cases we can specify that we want to use "multiprocess" futures as in:
+```r
+plan(multiprocess)
+```
+A multiprocess future is not a formal class of futures by itself, but rather a convenient alias for either of the two. When this is specified, multisession evaluation will be used unless multicore evaluation is supported.
+
+
+#### Cluster Futures
+Cluster futures evaluate expressions on an ad-hoc cluster (as implemented by the parallel package). For instance, assume you have access to three nodes `n1`, `n2` and `n3`, you can then use these for asynchronous evaluation as:
+```r
+> plan(cluster, workers = c("n1", "n2", "n3"))
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ pid <- Sys.getpid()
++ cat("Resolving 'a' ...\n")
++ 3.14
++ }
+> b %<-% {
++ rm(pid)
++ cat("Resolving 'b' ...\n")
++ Sys.getpid()
++ }
+> c %<-% {
++ cat("Resolving 'c' ...\n")
++ 2 * a
++ }
+> b
+[1] 28115
+> c
+[1] 6.28
+> a
+[1] 3.14
+> pid
+[1] 28072
+```
+Just as for the other asynchronous evaluation strategies, the output from `cat()` is not displayed on the current/calling machine.
+
+
+Any types of clusters that `parallel::makeCluster()` creates can be used for cluster futures. For instance, the above cluster can be explicitly set up as:
+```r
+cl <- parallel::makeCluster(c("n1", "n2", "n3"))
+plan(cluster, workers=cl)
+```
+Also, it is considered good style to shut down the cluster when it is no longer needed, that is, calling `parallel::stopCluster(cl)`. However, it will shut itself down if the main process is terminated, which will happen in the first example where the cluster in created internally. For more information on how to set up and manage such clusters, see `help("makeCluster", package="parallel")`.
+
+Note that with proper firewall and router configurations (e.g. port forwarding) and with automatic authentication setup (e.g. SSH key pairs), there is nothing preventing us from using the same approach for using a cluster of remote machines.
+
+
+
+### Different Strategies for Different Futures
+Sometimes one may want to use an alternative evaluation strategy for a specific future. Although one can use `old <- plan(new)` and afterward `plan(old)` to temporarily switch strategies, a simpler approach is to use the `%plan%` operator, e.g.
+```r
+> plan(eager)
+> pid <- Sys.getpid()
+> pid
+[1] 28072
+> a %<-% {
++ Sys.getpid()
++ }
+> b %<-% {
++ Sys.getpid()
++ } %plan% multiprocess
+> c %<-% {
++ Sys.getpid()
++ } %plan% multiprocess
+> a
+[1] 28072
+> b
+[1] 28132
+> c
+[1] 28133
+```
+As seen by the different process IDs, future `a` is evaluated eagerly using the same process as the calling environment whereas the other two are evaluated using multiprocess futures.
+
+
+
+
+However, using different plans to individual futures this way has the drawback of hard coding the evaluation strategy. Doing so may prevent some users from using your script or your package, because they do not have the sufficient resources. It may also prevent users with a lot of resources from utilizing those because you assumed a less-powerful set of hardware. Because of this, we recommend against the use of `%plan%` other than for interactive prototyping.
+
+
+### Nested Futures and Evaluation Topologies
+This far we have discussed what can be referred to as "flat topology" of futures, that is, all futures are created in and assigned to the same environment. However, there is nothing stopping us from using a "nested topology" of futures, where one set of futures may, in turn, create another set of futures internally and so on.
+
+For instance, here is an example of two "top" futures (`a` and `b`) that uses multiprocess evaluation and where the second future (`b`) in turn uses two internal futures:
+```r
+> plan(multiprocess)
+> pid <- Sys.getpid()
+> a %<-% {
++ cat("Resolving 'a' ...\n")
++ Sys.getpid()
++ }
+> b %<-% {
++ cat("Resolving 'b' ...\n")
++ b1 %<-% {
++ cat("Resolving 'b1' ...\n")
++ Sys.getpid()
++ }
++ b2 %<-% {
++ cat("Resolving 'b2' ...\n")
++ Sys.getpid()
++ }
++ c(b.pid = Sys.getpid(), b1.pid = b1, b2.pid = b2)
++ }
+> pid
+[1] 28072
+> a
+[1] 28134
+> b
+ b.pid b1.pid b2.pid
+ 28135 28135 28135
+```
+By inspection the process IDs, we see that there are in total three different processes involved for resolving the futures. There is the main R process (pid 28072), and there are the two processes used by `a` (pid 28134) and `b` (pid 28135). However, the two futures (`b1` and `b2`) that is nested by `b` are evaluated by the same R process as `b`. This is because nested futures use eager evaluation unless otherwise specified. There are a few reasons for this, but the main reason is th [...]
+
+
+
+To specify a different type of _evaluation topology_, other than the first level of futures being resolved by multiprocess evaluation and the second level by eager evaluation, we can provide a list of evaluation strategies to `plan()`. First, the same evaluation strategies as above can be explicitly specified as:
+```r
+plan(list(multiprocess, eager))
+```
+We would actually get the same behavior if we try with multiple levels of multiprocess evaluations;
+```r
+> plan(list(multiprocess, multiprocess))
+[...]
+> pid
+[1] 28072
+> a
+[1] 28136
+> b
+ b.pid b1.pid b2.pid
+ 28137 28137 28137
+```
+The reason for this is, also here, to protect us from launching more processes than what the machine can support. Internally, this is done by setting `mc.cores` to zero ([sic!](https://github.com/HenrikBengtsson/Wishlist-for-R/issues/7)) such that no _additional_ parallel processes can be launched. This is the case for both multisession and multicore evaluation.
+
+
+Continuing, if we start off by eager evaluation and then use multiprocess evaluation for any nested futures, we get:
+```r
+> plan(list(eager, multiprocess))
+[...]
+Resolving 'a' ...
+Resolving 'b' ...
+> pid
+[1] 28072
+> a
+[1] 28072
+> b
+ b.pid b1.pid b2.pid
+ 28072 28138 28139
+```
+which clearly show that `a` and `b` are resolved in the calling process (pid 28072) whereas the two nested futures (`b1` and `b2`) are resolved in two separate R processes (pids 28138 and 28139).
+
+
+
+Having said this, it is indeed possible to use nested multiprocess evaluation strategies, if we explicitly specify (read _force_) the number of cores available at each level. In order to do this we need to "tweak" the default settings, which can be done as follows:
+```r
+> plan(list(tweak(multiprocess, workers = 3), tweak(multiprocess,
++ workers = 3)))
+[...]
+> pid
+[1] 28072
+> a
+[1] 28140
+> b
+ b.pid b1.pid b2.pid
+ 28141 28142 28145
+```
+First, we see that both `a` and `b` are resolved in different processes (pids 28140 and 28141) than the calling process (pid 28072). Second, the two nested futures (`b1` and `b2`) are resolved in yet two other R processes (pids 28142 and 28145).
+
+
+To clarify, when we set up the two levels of multiprocess evaluation, we specified that in total 3 processes may be used at each level. We choose three parallel processes, not just two, because one is always consumed by the calling process leaving two to be used for the asynchronous futures. This is why we see that `pid`, `a` and `b` are all resolved by the same process. If we had allowed only two cores at the top level, `a` and `b` would have been resolved by the same background proc [...]
+
+For more details on working with nested futures and different evaluation strategies at each level, see Vignette '[Futures in R: Future Topologies]'.
+
+
+### Checking A Future without Blocking
+It is possible to check whether a future has been resolved or not without blocking. This can be done using the `resolved(f)` function, which takes an explicit future `f` as input. If we work with implicit futures (as in all the examples above), we can use the `f <- futureOf(a)` function to retrieve the explicit future from an implicit one. For example,
+```r
+> plan(multiprocess)
+> a %<-% {
++ cat("Resolving 'a' ...")
++ Sys.sleep(2)
++ cat("done\n")
++ Sys.getpid()
++ }
+> cat("Waiting for 'a' to be resolved ...\n")
+Waiting for 'a' to be resolved ...
+> f <- futureOf(a)
+> count <- 1
+> while (!resolved(f)) {
++ cat(count, "\n")
++ Sys.sleep(0.2)
++ count <- count + 1
++ }
+1
+2
+3
+4
+5
+> cat("Waiting for 'a' to be resolved ... DONE\n")
+Waiting for 'a' to be resolved ... DONE
+> a
+[1] 28146
+```
+
+
+## Failed Futures
+Sometimes the future is not what you expected. If an error occurs while evaluating a future, the error is propagated and thrown as an error in the calling environment _when the future value is requested_. For example,
+```r
+> plan(lazy)
+> a %<-% {
++ cat("Resolving 'a' ...\n")
++ stop("Whoops!")
++ 42
++ }
+> cat("Everything is still ok although we have created a future that will fail.\n")
+Everything is still ok although we have created a future that will fail.
+> a
+Resolving 'a' ...
+Error in eval(expr, envir, enclos) : Whoops!
+```
+The error is thrown each time the value is requested, that is, if we try to get the value again will generate the same error:
+```r
+> a
+Error in eval(expr, envir, enclos) : Whoops!
+In addition: Warning message:
+restarting interrupted promise evaluation
+```
+To see the list of calls (evaluated expressions) that lead up to the error, we can use the `backtrace()` function(*) on the future, i.e.
+```r
+> backtrace(a)
+[[1]]
+eval(quote({
+ cat("Resolving 'a' ...\n")
+ stop("Whoops!")
+ 42
+}), new.env())
+[[2]]
+eval(expr, envir, enclos)
+[[3]]
+stop("Whoops!")
+```
+(*) The commonly used `traceback()` does not provide relevant information in the context of futures.
+
+
+## Globals
+Whenever an R expression is to be evaluated asynchronously (in parallel) or via lazy evaluation, global objects have to be identified and passed to the evaluator. They need to be passed exactly as they were at the time the future was created, because, for a lazy future, globals may otherwise change between when it is created and when it is resolved. For asynchronous processing, the reason globals need to be identified is so that they can be exported to the process that evaluates the future.
+
+The future package tries to automate these tasks as far as possible. It does this with help of the [globals] package. If a global variable is identified, it is captured and made available to the evaluating process.
+Moreover, if a global is defined in a package, then that global is not exported. Instead, it is made sure that the corresponding package is attached when the future is evaluated. This not only better reflects the setup of the main R session, but it also minimizes the need for exporting globals, which saves not only memory but also time and bandwidth, especially when using remote compute nodes.
+
+Finally, it should be clarified that identifying globals from static code inspection alone is a challenging problem. There will always be corner cases where automatic identification of globals fails so that either false globals are identified (less of a concern) or some of the true globals are missing (which will result in a runtime error or possibly the wrong results). Vignette '[Futures in R: Common Issues with Solutions]' provides examples of common cases and explains how to avoid t [...]
+
+
+
+## Constraints when using Implicit Futures
+
+There is one limitation with implicit futures that does not exist for explicit ones. Because an explicit future is just like any other object in R it can be assigned anywhere/to anything. For instance, we can create several of them in a loop and assign them to a list, e.g.
+```r
+> plan(multiprocess)
+> f <- list()
+> for (ii in 1:3) {
++ f[[ii]] <- future({
++ Sys.getpid()
++ })
++ }
+> v <- lapply(f, FUN = value)
+> str(v)
+List of 3
+ $ : int 28147
+ $ : int 28148
+ $ : int 28149
+```
+This is _not_ possible to do when using implicit futures. This is because the `%<-%` assignment operator _cannot_ be used in all cases where the regular `<-` assignment operator can be used. It can only be used to assign future values to _environments_ (including the calling environment) much like how `assign(name, value, envir)` works. However, we can assign implicit futures to environments using _named indices_, e.g.
+```r
+> plan(multiprocess)
+> v <- new.env()
+> for (name in c("a", "b", "c")) {
++ v[[name]] %<-% {
++ Sys.getpid()
++ }
++ }
+> v <- as.list(v)
+> str(v)
+List of 3
+ $ a: int 28150
+ $ b: int 28151
+ $ c: int 28152
+```
+Here `as.list(v)` blocks until all futures in the environment `v` have been resolved. Then their values are collected and returned as a regular list.
+
+If _numeric indices_ are required, then _list environments_ can be used. List environments, which are implemented by the [listenv] package, are regular environments with customized subsetting operators making it possible to index them much like how lists can be indexed. By using list environments where we otherwise would use lists, we can also assign implicit futures to list-like objects using numeric indices. For example,
+```r
+> library("listenv")
+> plan(multiprocess)
+> v <- listenv()
+> for (ii in 1:3) {
++ v[[ii]] %<-% {
++ Sys.getpid()
++ }
++ }
+> v <- as.list(v)
+> str(v)
+List of 3
+ $ : int 28153
+ $ : int 28154
+ $ : int 28155
+```
+As previously, `as.list(v)` blocks until all futures are resolved.
+
+
+
+## Demos
+To see a live illustration how different types of futures are evaluated, run the Mandelbrot demo of this package. First, try with the eager evaluation,
+```r
+library("future")
+plan(eager)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+which closely imitates how the script would run if futures were not used. Then try the same using lazy evaluation,
+```r
+plan(lazy)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+and see if you can notice the difference in how and when statements are evaluated.
+You may also try multiprocess evaluation, which calculates the different Mandelbrot planes using parallel R processes running in the background. Try,
+```r
+plan(multiprocess)
+demo("mandelbrot", package="future", ask=FALSE)
+```
+This will use multicore processing if you are on a system where R supports process forking, otherwise (such as on Windows) it will use multisession processing.
+
+Finally, if you have access to multiple machines you can try to set up a cluster of workers and use them, e.g.
+```r
+plan(cluster, workers=c("n2", "n5", "n6", "n6", "n9"))
+demo("mandelbrot", package="future", ask=FALSE)
+```
+
+
+
+## Contributing
+The goal of this package is to provide a standardized and unified API for using futures in R. What you are seeing right now is an early but sincere attempt to achieve this goal. If you have comments or ideas on how to improve the 'future' package, I would love to hear about them. The preferred way to get in touch is via the [GitHub repository](https://github.com/HenrikBengtsson/future/), where you also find the latest source code. I am also open to contributions and collaborations of [...]
+
+
+[BatchJobs]: http://cran.r-project.org/package=BatchJobs
+[future]: http://cran.r-project.org/package=future
+[future.BatchJobs]: http://cran.r-project.org/package=future.BatchJobs
+[globals]: http://cran.r-project.org/package=globals
+[listenv]: http://cran.r-project.org/package=listenv
+[Futures in R: Common Issues with Solutions]: future-2-issues.html
+[Futures in R: Future Topologies]: future-3-topologies.html
+---
+Copyright Henrik Bengtsson, 2015-2016
diff --git a/vignettes/future-2-issues.md.rsp b/vignettes/future-2-issues.md.rsp
index bd916df..68a6641 100644
--- a/vignettes/future-2-issues.md.rsp
+++ b/vignettes/future-2-issues.md.rsp
@@ -69,6 +69,42 @@ A workaround is to explicitly tell the future package about the global variable
_Comment_: The goal is that the [globals] package will also handle the above case in a future version.
+#### Global variable specified as part of formula
+Global variables that are part of formulas are currently not identified automatically. For example,
+```r
+> library("future")
+> plan(multisession)
+>
+> x <- 1:10
+> y <- rnorm(10)
+> fit %<-% lm(y ~ x)
+> fit
+Received error on future: 'Error: object 'y' not found
+'
+Future state: 'failed'
+Future value: 'Error: object 'y' not found
+'
+Error: object 'y' not found
+```
+
+The workaround is to guide R by specifying such variables explicitly, e.g.
+```r
+> fit %<-% {
++ x; y ## Force 'x' and 'y' to be global
++ lm(y ~ x)
++ }
+> fit
+
+Call:
+lm(formula = y ~ x)
+
+Coefficients:
+(Intercept) x
+ -0.40506 0.01751
+```
+
+_Comment_: The goal is that the [globals] package will also handle the above case in a future version.
+
#### do.call() - function not found
When calling a function using `do.call()` make sure to specify the function as the object itself and not by name. This will help identify the function as a global object in the future expression. For instance, use
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/r-cran-future.git
More information about the debian-med-commit
mailing list