update docs

R/daemons.R

@@ -61,17 +61,13 @@
 #' @param remote [default NULL] required only for launching remote daemons, a
 #'   configuration generated by \code{\link{remote_config}} or
 #'   \code{\link{ssh_config}}.
-#' @param dispatcher [default 'process'] character value, one of
-#'   \sQuote{process}, \sQuote{next}, or \sQuote{none}. Whether to deploy
-#'   dispatcher in another process, on a thread or not at all. Dispatcher is an
-#'   extension that ensures optimal scheduling, although this is not always
-#'   required (for details see Dispatcher section below).
+#' @param dispatcher [default 'process'] character value, either
+#'   \sQuote{default}, or \sQuote{none}, whether to use dispatcher. Dispatcher
+#'   runs in a separate process to ensure optimal scheduling, although this is
+#'   not always required (for details see Dispatcher section below).
 #' @param ... (optional) additional arguments passed through to
-#'   \code{\link{dispatcher}} if using dispatcher and/or \code{\link{daemon}} if
-#'   launching daemons. These include \sQuote{retry} and \sQuote{token} at
-#'   dispatcher and \sQuote{asyncdial}, \sQuote{autoexit}, \sQuote{cleanup},
-#'   \sQuote{output}, \sQuote{maxtasks}, \sQuote{idletime}, \sQuote{walltime}
-#'   and \sQuote{timerstart} at daemon.
+#'   \code{\link{daemon}} if launching daemons. These include \sQuote{asyncdial},
+#'   \sQuote{autoexit}, \sQuote{cleanup} and \sQuote{output}.
 #' @param force [default TRUE] logical value whether to always reset daemons and
 #'   apply new settings for a compute profile, even if already set. If FALSE,
 #'   applying new settings requires daemons to be explicitly reset first using
@@ -130,6 +126,9 @@
 #' to use TLS. The auxiliary function \code{\link{host_url}} may be used to
 #' automatically construct a valid host URL based on the computer's hostname.
 #'
+#' \sQuote{n} is not required in this case, and disregarded if supplied, as
+#' network resources may be added or removed at any time.
+#'
 #' Specify \sQuote{remote} with a call to \code{\link{remote_config}} or
 #' \code{\link{ssh_config}} to launch daemons on remote machines. Otherwise,
 #' \code{\link{launch_remote}} may be used to generate the shell commands to
@@ -145,47 +144,18 @@
 #' free ephemeral port. Use \code{\link{status}} to inspect the actual assigned
 #' port at any time.
 #'
-#' \strong{With Dispatcher}
-#'
-#' When using dispatcher, it is recommended to use a websocket URL rather than
-#' TCP, as this requires only one port to connect to all daemons: a websocket
-#' URL supports a path after the port number, which can be made unique for each
-#' daemon.
-#'
-#' Specifying a single host URL such as \sQuote{ws://10.75.32.70:5555} with
-#' \code{n = 6} will automatically append a sequence to the path, listening to
-#' the URLs \sQuote{ws://10.75.32.70:5555/1} through
-#' \sQuote{ws://110.75.32.70:5555/6}.
-#'
-#' Alternatively, specify a vector of URLs to listen to arbitrary port numbers /
-#' paths. In this case it is optional to supply \sQuote{n} as this can be
-#' inferred by the length of vector supplied.
-#'
-#' Individual daemons then dial in to each of these host URLs. At most one
-#' daemon can be dialled into each URL at any given time.
+#' When using dispatcher, it is recommended to use a TCP URL such as
+#' \sQuote{tcp://10.75.32.70:5555}. The host / dispatcher listens at this
+#' address, utilising a single port.
 #'
-#' Dispatcher automatically adjusts to the number of daemons actually connected.
-#' Hence it is possible to dynamically scale up or down the number of daemons as
-#' required, subject to the maximum number initially specified.
+#' Alternatively a websocket URL such as \sQuote{ws://10.75.32.70:5555/path}
+#' supports sharing the port with other applications by specifying a unique path
+#' after the port number.
 #'
-#' Alternatively, supplying a single TCP URL will listen at a block of URLs with
-#' ports starting from the supplied port number and incrementing by one for
-#' \sQuote{n} specified e.g. the host URL \sQuote{tcp://10.75.32.70:5555} with
-#' \code{n = 6} listens to the contiguous block of ports 5555 through 5560.
-#'
-#' \strong{Without Dispatcher}
-#'
-#' A TCP URL may be used in this case as the host listens at only one address,
-#' utilising a single port.
-#'
-#' The network topology is such that daemons (started with \code{\link{daemon}})
-#' or indeed dispatchers (started with \code{\link{dispatcher}}) dial into the
-#' same host URL.
-#'
-#' \sQuote{n} is not required in this case, and disregarded if supplied, as
-#' network resources may be added or removed at any time. The host automatically
-#' distributes tasks to all connected daemons and dispatchers in a round-robin
-#' fashion.
+#' Individual daemons (started with \code{\link{daemon}}) may then dial in to
+#' this URL. Host / dispatcher automatically adjusts to the number of daemons
+#' actually connected. Hence it is possible to dynamically scale up or down the
+#' number of daemons as required.
 #'
 #' @section Compute Profiles:
 #'

R/dispatcher.R

@@ -405,8 +405,8 @@ dispatcher_v1 <- function(host, url = NULL, n = NULL, ..., retry = FALSE, token
 
 #' Saisei (Regenerate Token)
 #'
-#' When using daemons with dispatcher, regenerates the token for the URL a
-#' dispatcher socket listens at.
+#' When using daemons with the legacy v1 dispatcher, regenerates the token for
+#' the URL a dispatcher socket listens at.
 #'
 #' When a URL is regenerated, the listener at the specified socket is closed and
 #' replaced immediately, hence this function will only be successful if there
@@ -419,8 +419,6 @@ dispatcher_v1 <- function(host, url = NULL, n = NULL, ..., retry = FALSE, token
 #' cancel a task that consistently hangs or crashes to prevent it from failing
 #' repeatedly when new daemons connect.
 #'
-#' Has no effect and returns NULL if using \sQuote{next} dispatcher.
-#'
 #' @inheritParams mirai
 #' @param i integer index number URL to regenerate at dispatcher.
 #' @param force [default FALSE] logical value whether to regenerate the URL even
@@ -444,7 +442,7 @@ dispatcher_v1 <- function(host, url = NULL, n = NULL, ..., retry = FALSE, token
 #' if (interactive()) {
 #' # Only run examples in interactive R sessions
 #'
-#' daemons(1L)
+#' daemons(1L, dispatcher = "process")
 #' Sys.sleep(1L)
 #' status()
 #' saisei(i = 1L, force = TRUE)

R/launchers.R

@@ -33,10 +33,10 @@
 #' @inheritParams mirai
 #' @param url the character host URL or vector of host URLs, including the port
 #'   to connect to (and optionally for websockets, a path), e.g.
-#'   'tcp://hostname:5555' or 'ws://10.75.32.70:5555/path'
+#'   'tcp://hostname:5555' or 'ws://10.75.32.70:5555/path',
 #'
-#'   \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} 1L, or a vector of 1Ls, to use the host / dispatcher URL
+#'   from the compute profile,
 #'
 #'   \strong{or} for \code{launch_remote} only, a \sQuote{miraiCluster} or
 #'   \sQuote{miraiNode}.
@@ -61,16 +61,15 @@
 #'
 #' daemons(url = host_url(ws = TRUE), dispatcher = "none")
 #' status()
-#' launch_local(status()$daemons, maxtasks = 10L)
-#' launch_remote(1L, maxtasks = 10L)
+#' launch_local(nextget("urls"), cleanup = FALSE)
+#' launch_remote(1L, cleanup = FALSE)
 #' Sys.sleep(1)
 #' status()
 #' daemons(0)
 #'
-#' daemons(n = 2L, url = host_url(tls = TRUE))
+#' daemons(url = host_url(tls = TRUE))
 #' status()
-#' launch_local(1:2, idletime = 60000L, timerstart = 1L)
-#' launch_remote(1:2, idletime = 60000L, timerstart = 1L)
+#' launch_local(c(1L, 1L), output = TRUE)
 #' Sys.sleep(1)
 #' status()
 #' daemons(0)

R/map.R

@@ -90,7 +90,7 @@
 #' if (interactive()) {
 #' # Only run examples in interactive R sessions
 #'
-#' daemons(4, dispatcher = "next")
+#' daemons(4)
 #'
 #' # map with constant args specified via '.args'
 #' mirai_map(1:3, rnorm, .args = list(mean = 20, sd = 2))[]