implements remote_config() and ssh_config()

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: mirai
 Type: Package
 Title: Minimalist Async Evaluation Framework for R
-Version: 0.10.0.9022
+Version: 0.10.0.9023
 Description: Lightweight parallel code execution and distributed computing.
     Designed for simplicity, a 'mirai' evaluates an R expression asynchronously,
     on local or network resources, resolving automatically upon completion.

NAMESPACE

@@ -28,8 +28,9 @@ export(make_cluster)
 export(mirai)
 export(nextget)
 export(nextstream)
+export(remote_config)
 export(saisei)
-export(ssh_args)
+export(ssh_config)
 export(status)
 export(stop_cluster)
 export(stop_mirai)

NEWS.md

@@ -1,24 +1,23 @@
-# mirai 0.10.0.9022 (development)
+# mirai 0.10.0.9023 (development)
 
 * Implements an alternative communications backend for R, adding methods for the 'parallel' base package.
   + Fulfils a request by R Core at R Project Sprint 2023, and requires R >= 4.4 (currently R-devel).
   + `make_cluster()` creates a 'miraiCluster', compatible with all existing functions taking a 'cluster' object, for example in the 'parallel' and 'doParallel' / 'foreach' packages.
   + `status()` can now take a 'miraiCluster' as the argument to query its connection status.
-* Implements `ssh_args()` as a convenience function for constructing the correct arguments to launch remote daemons via SSH, including using reverse tunnelling.
-  + Argument signature of 'args' for `launch_remote()` changed to accommodate.
+* Implements `remote_config()` and `ssh_config()` to generate configurations for launching remote daemons generically, or via SSH, including using reverse tunnelling.
+  + `launch_remote()` simplified with a single 'remote' argument taking a remote configuration.
 * `daemons()` gains the following features:
-  + Adds arguments 'command', 'args' and 'rscript' for launching remote daemons automatically rather than needing to call `launch_remote()`.
+  + Adds argument 'remote' for launching remote daemons directly without recourse to a separate call to `launch_remote()`.
   + Adds argument 'resilience' to control the behaviour, when not using dispatcher, of whether to retry failed tasks on other daemons.
 * `mirai()` adds logical argument '.signal' for whether to signal the condition variable within the compute profile upon resolution of the 'mirai'.
-* `daemon()` argument 'exitlinger' retired as daemons now synchronise with the host/dispatcher and exit as soon as possible. Note: a default 'exitlinger' period still applies for ephemeral daemons.
+* `daemon()` argument 'exitlinger' retired as daemons now synchronise with the host/dispatcher and exit as soon as possible (although a default 'exitlinger' period still applies to ephemeral daemons).
 * Optimises scheduling at dispatcher: tasks are no longer assigned to a daemon if it is exiting due to specified time/task-outs.
 * An 'errorValue' 19 'Connection reset' is now returned for a 'mirai' if the connection to either dispatcher or an ephemeral daemon drops, for example if they have crashed, rather than remaining unresolved.
 * Invalid type of '...' arguments specified to `daemons()` or `dispatcher()` now raise an error early rather than attempting to launch daemons that fail.
 * Eliminates a potential crash in the host process after querying `status()` if there is no longer a connection to dispatcher.
 * Reverts the trailing line break added to the end of a 'miraiError' character string.
 * Deprecates the Deferred Evaluation Pipe `%>>%` in favour of a recommendation to use package `mirai.promises` for performing side effects upon 'mirai' resolution.
 * Deprecated use of alias `server()` for `daemon()` is retired.
-* Improved documentation for pass-through dot parameters (thanks @krlmlr #79).
 * Adds a 'reference' vignette, incorporating most of the information from the readme.
 * Requires nanonext >= 0.10.1.
 
@@ -80,7 +79,7 @@
 
 # mirai 0.8.7
 
-* `server()` and `dispatcher()` argument 'asyncdial' is now FALSE by default, causing these functions to exit if a connection is not immediately available. This means that for distributed computing purposes, `dameons()` should be called before `server()` is launched on remote resources, or else `server(asyncdial = TRUE)` allows servers to wait for a connection.
+* `server()` and `dispatcher()` argument 'asyncdial' is now FALSE by default, causing these functions to exit if a connection is not immediately available. This means that for distributed computing purposes, `daemons()` should be called before `server()` is launched on remote resources, or else `server(asyncdial = TRUE)` allows servers to wait for a connection.
 * `launch_server()` now parses the passed URL for correctness before attempting to launch a server, producing an error if not valid.
 
 # mirai 0.8.4

R/daemon.R

@@ -42,9 +42,9 @@
 #'     upon launch.
 #' @param output [default FALSE] logical value, to output generated stdout /
 #'     stderr if TRUE, or else discard if FALSE. Specify as TRUE in the '...'
-#'     argument to \code{\link{daemons}} or \code{\link{launch_local}} to
-#'     provide redirection of output to the host process (applicable only for
-#'     local daemons when not using dispatcher).
+#'     argument to \code{\link{daemons}} or \code{\link{launch_local}} to provide
+#'     redirection of output to the host process (applicable only for local
+#'     daemons when not using dispatcher).
 #' @param tls [default NULL] required for secure TLS connections over 'tls+tcp://'
 #'     or 'wss://'. \strong{Either} the character path to a file containing
 #'     X.509 certificate(s) in PEM format, comprising the certificate authority

R/daemons.R

@@ -38,9 +38,6 @@
 #'     Dispatcher is a local background process that connects to daemons on
 #'     behalf of the host and ensures FIFO scheduling (see Dispatcher section
 #'     below).
-#' @param resilience [default TRUE] (applicable when not using dispatcher)
-#'     logical value whether to retry failed tasks on other daemons. If FALSE,
-#'     an appropriate 'errorValue' will be returned in such cases.
 #' @param seed [default NULL] (optional) supply a random seed (single value,
 #'     interpreted as an integer). This is used to inititalise the L'Ecuyer-CMRG
 #'     RNG streams sent to each daemon. Note that reproducible results can be
@@ -56,10 +53,13 @@
 #'     chain, with the TLS certificate first), \strong{or} a length 2 character
 #'     vector comprising [i] the TLS certificate (optionally certificate chain)
 #'     and [ii] the associated private key.
-#' @param ... additional arguments passed through to \code{\link{dispatcher}} if
-#'     using dispatcher and/or \code{\link{daemon}} if launching daemons. These
-#'     include 'token' and 'lock' at dispatcher and 'maxtasks', 'idletime',
-#'     'timerstart', 'output' and 'cleanup' at daemon.
+#' @param ... (optional) additional arguments passed through to
+#'     \code{\link{dispatcher}} if using dispatcher and/or \code{\link{daemon}}
+#'     if launching daemons. These include 'token' and 'lock' at dispatcher and
+#'     'maxtasks', 'idletime', 'timerstart', 'output' and 'cleanup' at daemon.
+#' @param resilience [default TRUE] (applicable when not using dispatcher)
+#'     logical value whether to retry failed tasks on other daemons. If FALSE,
+#'     an appropriate 'errorValue' will be returned in such cases.
 #' @param .compute [default 'default'] character compute profile to use for
 #'     creating the daemons (each compute profile has its own set of daemons for
 #'     connecting to different resources).
@@ -256,16 +256,15 @@
 #' # Launch 4 daemons on a remote machine at 10.75.32.100 using SSH with
 #' # tunnelling on port 5555:
 #' #
-#' # daemons(n = 4, url = 'ws://localhost:5555', command = 'ssh',
-#' #         args = ssh_args('10.75.32.100', tunnel = TRUE))
+#' # daemons(n = 4, url = 'ws://localhost:5555',
+#' #         remote = ssh_config('ssh://10.75.32.100', tunnel = TRUE))
 #'
 #' }
 #'
 #' @export
 #'
-daemons <- function(n, url = NULL, dispatcher = TRUE, resilience = TRUE,
-                    seed = NULL, tls = NULL, pass = NULL, ...,  command = NULL,
-                    args = c("", "."), rscript = "Rscript", .compute = "default") {
+daemons <- function(n, url = NULL, remote = NULL, dispatcher = TRUE, seed = NULL,
+                    tls = NULL, pass = NULL, ..., resilience = TRUE, .compute = "default") {
 
   missing(n) && missing(url) && return(status(.compute))
 
@@ -301,8 +300,8 @@ daemons <- function(n, url = NULL, dispatcher = TRUE, resilience = TRUE,
         `[[<-`(envir, "urls", n)
       }
       `[[<-`(`[[<-`(`[[<-`(envir, "sock", sock), "n", n), "cv", cv())
-      if (length(command))
-        launch_remote(url = envir[["urls"]], ..., tls = envir[["tls"]], .compute = .compute, command = command, args = args, rscript = rscript)
+      if (length(remote))
+        launch_remote(url = envir[["urls"]], remote = remote, tls = envir[["tls"]], ..., .compute = .compute)
     }
 
   } else {

R/dispatcher.R

@@ -22,7 +22,6 @@
 #'     processing, using a FIFO scheduling rule, queuing tasks as required.
 #'
 #' @inheritParams daemon
-#' @inheritDotParams daemon maxtasks idletime walltime timerstart cleanup
 #' @param host the character host URL to dial (where tasks are sent from),
 #'     including the port to connect to (and optionally for websockets, a path),
 #'     e.g. 'tcp://10.75.32.70:5555' or 'ws://10.75.32.70:5555/path'.
@@ -51,6 +50,9 @@
 #' @param pass [default NULL] (required only if the private key supplied to 'tls'
 #'     is encrypted with a password) For security, should be provided through a
 #'     function that returns this value, rather than directly.
+#' @param ... (optional) additional arguments passed through to \code{\link{daemon}}.
+#'     These include 'maxtasks', 'idletime', 'walltime', 'timerstart', and
+#'     'cleanup'.
 #' @param monitor (for package internal use only) do not set this parameter.
 #'
 #' @return Invisible NULL.