From 5e41210566dd72f9419d88890b32aa1e3d2bbaf9 Mon Sep 17 00:00:00 2001 From: shikokuchuo <53399081+shikokuchuo@users.noreply.github.com> Date: Sun, 1 Dec 2024 19:53:48 +0000 Subject: [PATCH] update docs --- R/daemons.R | 68 +++++++++++++-------------------------------- R/dispatcher.R | 8 ++---- R/launchers.R | 15 +++++----- R/map.R | 2 +- man/daemons.Rd | 68 +++++++++++++-------------------------------- man/launch_local.Rd | 15 +++++----- man/mirai_map.Rd | 2 +- man/saisei.Rd | 8 ++---- 8 files changed, 60 insertions(+), 126 deletions(-) diff --git a/R/daemons.R b/R/daemons.R index 1c7ef9cd7..48977220d 100644 --- a/R/daemons.R +++ b/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: #' diff --git a/R/dispatcher.R b/R/dispatcher.R index cbc3f6461..e149fd127 100644 --- a/R/dispatcher.R +++ b/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) diff --git a/R/launchers.R b/R/launchers.R index fe394d4bf..15df2fabf 100644 --- a/R/launchers.R +++ b/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) diff --git a/R/map.R b/R/map.R index 07fb35c58..3756e8712 100644 --- a/R/map.R +++ b/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))[] diff --git a/man/daemons.Rd b/man/daemons.Rd index 0589804ef..746f53af9 100644 --- a/man/daemons.Rd +++ b/man/daemons.Rd @@ -31,18 +31,14 @@ function \code{\link{host_url}} may be used to construct a valid host URL.} configuration generated by \code{\link{remote_config}} or \code{\link{ssh_config}}.} -\item{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).} +\item{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).} \item{...}{(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}.} \item{force}{[default TRUE] logical value whether to always reset daemons and apply new settings for a compute profile, even if already set. If FALSE, @@ -150,6 +146,9 @@ which daemon processes should connect to. Switching the URL scheme to 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 @@ -165,47 +164,18 @@ Specifying the wildcard value zero for the port number e.g. 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}{ diff --git a/man/launch_local.Rd b/man/launch_local.Rd index 1cf33a33a..e42af0034 100644 --- a/man/launch_local.Rd +++ b/man/launch_local.Rd @@ -18,10 +18,10 @@ launch_remote( \arguments{ \item{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}.} @@ -80,16 +80,15 @@ if (interactive()) { 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) diff --git a/man/mirai_map.Rd b/man/mirai_map.Rd index 549d2779d..df58cd1bc 100644 --- a/man/mirai_map.Rd +++ b/man/mirai_map.Rd @@ -92,7 +92,7 @@ To map over \strong{columns} instead, first wrap a dataframe in 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))[] diff --git a/man/saisei.Rd b/man/saisei.Rd index bf9efefb9..702032891 100644 --- a/man/saisei.Rd +++ b/man/saisei.Rd @@ -19,8 +19,8 @@ to use (each compute profile has its own independent set of daemons).} The regenerated character URL upon success, or else NULL. } \description{ -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. } \details{ When a URL is regenerated, the listener at the specified socket is closed and @@ -33,8 +33,6 @@ regenerated. If this happens while a mirai task is still ongoing, it will be returned as an \sQuote{errorValue} 7 (Object closed). This may be used to 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. } \section{Timeouts}{ @@ -54,7 +52,7 @@ any particular URL for a new \code{\link{daemon}} to connect to. if (interactive()) { # Only run examples in interactive R sessions -daemons(1L) +daemons(1L, dispatcher = "process") Sys.sleep(1L) status() saisei(i = 1L, force = TRUE)