fastRCluster: add function fastr as a simpler wrapper around clusterApply

Author: steve-s

com.oracle.truffle.r.pkgs/fastRCluster/NAMESPACE

@@ -3,6 +3,7 @@
 S3method(print,fastRCluster)
 export(defaultGraalVMHome)
 export(fastRClusterInstallPackages)
+export(fastr)
 export(getGraalVMHome)
 export(installFastR)
 export(makeFastRCluster)

com.oracle.truffle.r.pkgs/fastRCluster/R/fastRCluster.R

@@ -61,16 +61,21 @@
 #' installFastR()
 #'
 #' # use the cluster package with FastR
-#' cl <- makeFastRCluster()
-#' print(cl)
+#' fastrNode <- makeFastRCluster()
+#' print(fastrNode)
 #' # prints: FastR socket cluster with 1 nodes on host ‘localhost’
 #'
 #' # install required packages on FastR
 #' fastRClusterInstallPackages('rlang')
 #'
 #' # use the cluster package with FastR
 #' # R.version will show that we are running that code on FastR
-#' parallel::clusterApply(cl, 'dummy', function(...) R.version)
+#' parallel::clusterApply(fastrNode, 'dummy', function(...) R.version)
+#'
+#' # use 'fastr' convenient wrapper around clusterApply
+#' gg <- fastr(fastrNode, ggplot2::qplot(mpg, data=mtcars, geom="density",
+#'   main=paste0("Generated by ", R.version$engine, "[", Sys.getpid(), "]")))
+#' plot(gg)
 #'
 #' # transfer data and a helper function to the global environmnet of the cluster nodes
 #' largeDataSet <- matrix(runif(1000000), 1000, 1000)
@@ -87,9 +92,9 @@
 #'   }
 #'   res
 #' }
-#' parallel::clusterExport(cl, c('largeDataSet', 'myComputation'))
+#' parallel::clusterExport(fastrNode, c('largeDataSet', 'myComputation'))
 #' # now you can refer to 'largeDataSet' and 'myComputation'
-#' parallel::clusterApply(cl, 'dummy', function(...) myComputation(largeDataSet))
+#' fastr(fastrNode, myComputation(largeDataSet))
 #'
 #' # use the future package with FastR
 #' if (require(future)) {
@@ -190,6 +195,8 @@ installFastR <- function(path = defaultGraalVMHome()) {
 #' @param ... Parameters passed to the R function \code{install.packages} that is run on the FastR engine.
 #' @return Invisible \code{NULL}
 #' @export
+#' @examples
+#' fastRClusterInstallPackages(c('rlang', 'ggplot2'), INSTALL_opts='--no-test-load')
 fastRClusterInstallPackages <- function(...) {
     cl <- makeFastRCluster(1, metehods=F)
     on.exit(stopCluster(cl))
@@ -213,8 +220,9 @@ fastRClusterInstallPackages <- function(...) {
 #' @seealso \code{\link{getGraalVMHome}}
 #' @export
 #' @examples
-#' cl <- makeFastRCluster()
-#' parallel::clusterApply(cl, 'dummy', function(...) R.version)
+#' fastrNode <- makeFastRCluster()
+#' parallel::clusterApply(fastrNode, 'dummy', function(...) R.version)
+#' fastr(fastrNode, R.version)
 makeFastRCluster <- function (nnodes = 1L, graalVMHome = getGraalVMHome(), mode = c('jvm', 'native'), polyglot = FALSE, fastROptions = NULL, ...) {
     nnodes <- as.integer(nnodes)
     if(is.na(nnodes) || nnodes < 1L) {
@@ -224,20 +232,21 @@ makeFastRCluster <- function (nnodes = 1L, graalVMHome = getGraalVMHome(), mode
 
     if (!dir.exists(graalVMHome)) {
         if (graalVMHome == defaultGraalVMHome()) {
-            stop(sprintf(paste0("It seems that FastR was not installed yet.\n",
+            stop(sprintf(paste0("It seems that FastR was not installed yet. ",
                 "Use installFastR() to install GraalVM and FastR to the default location '%s', ",
-                "or set argument 'path' to a directory that contains GraalVM and FastR installation.", defaultGraalVMHome())))
+                "or set argument 'graalVMHome' to a directory that contains GraalVM and FastR installation. ",
+                "See ?getGraalVMHome for more details."), defaultGraalVMHome()))
         } else {
-            stop(sprintf(paste0("The GraalVM directory '%s' does not exist.\n",
+            stop(sprintf(paste0("The GraalVM directory '%s' does not exist. ",
                 "Use installFastR('%s') to install GraalVM and FastR to that directory."),
                 graalVMHome, graalVMHome))
         }
     }
     if (!file.exists(file.path(graalVMHome, 'bin', 'gu'))) {
-        stop(sprintf("The GraalVM directory '%s' appears to be corrupt.\nYou can remove it and use installFastR('%s') to re-install GraalVM and FastR.", graalVMHome, graalVMHome))
+        stop(sprintf("The GraalVM directory '%s' appears to be corrupt. You can remove it and use installFastR('%s') to re-install GraalVM and FastR.", graalVMHome, graalVMHome))
     }
     if (!file.exists(file.path(graalVMHome, 'bin', 'Rscript'))) {
-        stop(sprintf("The GraalVM installation '%s' does not contain FastR.\nUse installFastR('%s') to install FastR.", graalVMHome, graalVMHome))
+        stop(sprintf("The GraalVM installation '%s' does not contain FastR. Use installFastR('%s') to install FastR.", graalVMHome, graalVMHome))
     }
     if (any(c('--jvm', '--native') %in% fastROptions)) {
        warning("Ignoring --jvm/--native in 'fastROptions' argument. Use the 'mode' argument instead.")
@@ -265,6 +274,22 @@ makeFastRCluster <- function (nnodes = 1L, graalVMHome = getGraalVMHome(), mode
     result
 }
 
+#' Runs given code in the FastR engine.
+#'
+#' This is a convenient wrapper around \code{clusterApply} that runs
+#' the given code on the first node in the cluster.
+#'
+#' @param cl FastR cluster object. Use \code{\link{makeFastRCluster}()} to get one.
+#' @param code The code that will be run on the FastR node. It will not be evaluated in the current session.
+#' @return The result of evaluating the code
+#' @export
+#' @examples
+#' fastrNode <- makeFastRCluster()
+#' fastr(fastrNode, R.version)
+fastr <- function(cl, code) {
+    parallel::clusterApply(cl, 'dummy', function(...) code)[[1L]]
+}
+
 #' @export
 print.fastRCluster <- function(x, ...) {
    cat("FastR "); NextMethod(x, ...)