update docs

NEWS.md

@@ -7,6 +7,7 @@
 * `launch_remote()` improvements:
   + Simplified interface with a single 'remote' argument taking a remote configuration to launch daemons.
   + Returned shell commands now have a custom print method which means they may be directly copy/pasted to a remote machine.
+  + Can now take a 'miraiCluster' or 'miraiNode' to return the shell commands for deployment of remote nodes.
 * `daemons()` gains the following features:
   + 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.

R/daemons.R

@@ -87,7 +87,7 @@
 #'
 #'     If the host session ends, for whatever reason, all connected dispatcher
 #'     and daemon processes automatically exit as soon as their connections are
-#'     dropped. If a daemon is procesing a task, it will exit as soon as the
+#'     dropped. If a daemon is processing a task, it will exit as soon as the
 #'     task is complete.
 #'
 #'     For historical reasons, \code{daemons()} with no arguments returns the

R/launchers.R

@@ -29,7 +29,7 @@
 #'     \strong{or} integer index value, or vector of index values, of the
 #'     dispatcher URLs, or 1L for the host URL (when not using dispatcher).
 #'
-#'     \strong{or} for \code{launch_remote} only, a 'miraiCluster'.
+#'     \strong{or} for \code{launch_remote} only, a 'miraiCluster' or 'miraiNode'.
 #' @param ... (optional) additional arguments passed through to
 #'     \code{\link{daemon}}. These include 'asyncdial', 'maxtasks', 'idletime',
 #'     'walltime', 'timerstart', 'output' and 'cleanup'.
@@ -110,9 +110,9 @@ launch_local <- function(url, ..., tls = NULL, .compute = "default") {
 #'
 launch_remote <- function(url, remote = remote_config(), ..., tls = NULL, .compute = "default") {
 
-  if (is.list(url) && inherits(url, "miraiCluster")) {
+  if (!is.character(url) && inherits(url, c("miraiCluster", "miraiNode"))) {
     .compute <- attr(url, "id")
-    url <- 1L
+    url <- rep(..[[.compute]][["urls"]], max(length(url), 1L))
   }
   envir <- ..[[.compute]]
   dots <- parse_dots(...)

R/parallel.R

@@ -26,46 +26,59 @@
 #'     package such as \code{\link[parallel]{clusterApply}} or
 #'     \code{\link[parallel]{parLapply}}.
 #'
-#' @param n integer number of nodes (launched on the local machine unless 'url'
-#'     is specified).
-#' @param url [default NULL] if connecting to remote nodes, the character URL on
-#'     the host for remote nodes to dial into, including a port accepting
-#'     incoming connections, e.g. 'tcp://10.75.37.40:5555'. Specify a URL
-#'     starting 'tls+tcp://' to use secure TLS connections.
-#' @param remote [default NULL] required only for launching remote nodes, a
-#'     configuration generated by \code{\link{remote_config}} or
-#'     \code{\link{ssh_config}}. If not specified, nodes connecting to 'url' may
-#'     be launched manually.
+#' @param n integer number of nodes (automatically launched on the local machine
+#'     unless 'url' is supplied).
+#' @param url [default NULL] (specify for remote nodes) the character URL on the
+#'     host for remote nodes to dial into, including a port accepting incoming
+#'     connections, e.g. 'tcp://10.75.37.40:5555'. Specify a URL with the scheme
+#'     'tls+tcp://' to use secure TLS connections.
+#' @param remote [default NULL] (specify to launch remote nodes) a remote launch
+#'     configuration generated by \code{\link{remote_config}} or \code{\link{ssh_config}}.
+#'     If not supplied, nodes may be deployed manually on remote resources.
 #' @param ... additional arguments passed onto \code{\link{daemons}}.
 #'
 #' @return For \strong{make_cluster}: An object of class 'miraiCluster' and
 #'     'cluster'. Each 'miraiCluster' has an automatically assigned ID and 'n'
-#'     nodes of class 'miraiNode'.
+#'     nodes of class 'miraiNode'. If 'url' is supplied but not 'remote', the
+#'     shell commands for deployment of nodes on remote resources is printed in
+#'     interactive sessions.
 #'
 #'     For \strong{stop_cluster}: invisible NULL.
 #'
-#' @details The default behaviour of clusters created by this function is
-#'     designed to map as closely as possible to clusters created by the
-#'     \pkg{parallel} package. However, '...' arguments are passed onto
-#'     \code{\link{daemons}} for additional customisation if desired.
+#' @section Remote Nodes:
 #'
-#'     Call \code{\link{status}} on a 'miraiCluster' to check the number of
-#'     currently active connections as well as the host URL.
+#'     Specify 'n' and 'url' to set up a host connection for remote nodes to
+#'     dial into.
 #'
-#' @section Remote Nodes:
+#'     Also specify 'remote' to launch the nodes using a configuration generated
+#'     by \code{\link{remote_config}} or \code{\link{ssh_config}}. In this case,
+#'     the number of nodes is inferred from the configuration provided and 'n'
+#'     is disregarded.
+#'
+#'     If 'remote' is not supplied, the shell commands for deploying nodes
+#'     manually on remote resources are automatically printed in interactive
+#'     sessions.
 #'
-#'     If 'remote' is specified, the number of nodes is inferred from the
-#'     configuration provided and 'n' is disregarded.
+#'     \code{\link{launch_remote}} may be called at any time on a 'miraiCluster'
+#'     to return the shell commands for deployment of all nodes, or on a
+#'     'miraiNode' to return the command for a single node.
 #'
-#'     Alternatively, by specifying only 'url' and 'n', the host connection
-#'     listening at 'url' is set up, and nodes may be launched by other custom
-#'     means.
+#' @section Status:
+#'
+#'     Call \code{\link{status}} on a 'miraiCluster' to check the number of
+#'     currently active connections as well as the host URL.
 #'
 #' @note Requires R >= 4.4 (currently R-devel). Clusters created with this
 #'     function will not work with prior R versions. The functionality is
 #'     experimental prior to release of R 4.4 and the interface is consequently
 #'     subject to change at any time.
 #'
+#'     The default behaviour of clusters created by this function is
+#'     designed to map as closely as possible to clusters created by the
+#'     \pkg{parallel} package. However, '...' arguments are passed onto
+#'     \code{\link{daemons}} for additional customisation if desired, although
+#'     resultant behaviour may not be supported.
+#'
 #' @examples
 #' if (interactive()) {
 #' # Only run examples in interactive R sessions
@@ -86,6 +99,7 @@
 make_cluster <- function(n, url = NULL, remote = NULL, ...) {
 
   id <- sprintf("`%d`", length(..))
+  printLaunchCmd <- FALSE
 
   if (is.character(url)) {
 
@@ -96,7 +110,10 @@ make_cluster <- function(n, url = NULL, remote = NULL, ...) {
       n <- if (is.list(args)) length(args) else 1L
     } else {
       missing(n) && stop(.messages[["requires_n"]])
-      message(sprintf("%d nodes connecting to '%s' should be launched manually", n, url))
+      if (interactive()) {
+        message("Shell commands for deployment on nodes:")
+        printLaunchCmd <- TRUE
+      }
     }
 
     daemons(url = url, remote = remote, dispatcher = FALSE, resilience = FALSE,
@@ -114,6 +131,9 @@ make_cluster <- function(n, url = NULL, remote = NULL, ...) {
     cl[[i]] <- `attributes<-`(new.env(), list(class = "miraiNode", node = i, id = id))
   reg.finalizer(cl[[1L]], stop_cluster, TRUE)
 
+  if (printLaunchCmd)
+    print(launch_remote(rep(..[[id]][["urls"]], n), .compute = id))
+
   `attributes<-`(cl, list(class = c("miraiCluster", "cluster"), id = id))
 
 }

README.Rmd

@@ -117,7 +117,7 @@ vignette("reference", package = "mirai")
 
 ### Use with Parallel
 
-`mirai` provides an alternative communications backend for R's base 'parallel' package. The `make_cluster()` function creates a 'miraiCluster', which leverages the full capabilities of the package, but remains fully compatible with all `parallel` functions such as `clusterApply` or `parLapply`.
+`mirai` provides an alternative communications backend for R's base 'parallel' package. The `make_cluster()` function creates a 'miraiCluster', which leverages the full capabilities of the package, but remains fully compatible with all `parallel` functions such as `parallel::clusterApply()`, `parallel::parLapply()` or `parallel::parLapplyLB()`.
 
 Created clusters may also be used in all cases which take a 'cluster' object. For example, [`doParallel`](https://cran.r-project.org/package=doParallel) may be used to register a 'miraiCluster' for use with the package [`foreach`](https://cran.r-project.org/package=foreach).
 

README.md

@@ -90,17 +90,17 @@ result.
 
 ``` r
 m$data
-#>  [1]  1.0711517 -0.2350287  0.5452594 -3.4220150 -1.5016444  1.0000000
-#>  [7] -0.6659366 -0.2922255  1.8339895 -4.2547997  0.9335746
+#>  [1] -0.31834109 -0.63736917  0.84783942  0.01343468  0.46308687  1.00000000
+#>  [7]  2.15942205 74.43423993  1.17946863 -1.56894945 -3.14128469
 ```
 
 Alternatively, explicitly call and wait for the result using
 `call_mirai()`.
 
 ``` r
 call_mirai(m)$data
-#>  [1]  1.0711517 -0.2350287  0.5452594 -3.4220150 -1.5016444  1.0000000
-#>  [7] -0.6659366 -0.2922255  1.8339895 -4.2547997  0.9335746
+#>  [1] -0.31834109 -0.63736917  0.84783942  0.01343468  0.46308687  1.00000000
+#>  [7]  2.15942205 74.43423993  1.17946863 -1.56894945 -3.14128469
 ```
 
 ### Reference Vignette
@@ -127,7 +127,8 @@ vignette("reference", package = "mirai")
 ‘parallel’ package. The `make_cluster()` function creates a
 ‘miraiCluster’, which leverages the full capabilities of the package,
 but remains fully compatible with all `parallel` functions such as
-`clusterApply` or `parLapply`.
+`parallel::clusterApply()`, `parallel::parLapply()` or
+`parallel::parLapplyLB()`.
 
 Created clusters may also be used in all cases which take a ‘cluster’
 object. For example,