update docs and readme

R/daemon.R

@@ -24,18 +24,13 @@
 #'
 #' @param url the character host or dispatcher URL to dial into, including the
 #'     port to connect to (and optionally for websockets, a path), e.g.
-#'     'tcp://192.168.0.2:5555' or 'ws://192.168.0.2:5555/path'.
+#'     'tcp://10.75.32.70:5555' or 'ws://10.75.32.70:5555/path'.
 #' @param asyncdial [default FALSE] whether to perform dials asynchronously. The
 #'     default FALSE will error if a connection is not immediately possible
 #'     (e.g. \code{\link{daemons}} has yet to be called on the host, or the
 #'     specified port is not open etc.). Specifying TRUE continues retrying
 #'     (indefinitely) if not immediately successful, which is more resilient but
 #'     can mask potential connection issues.
-#' @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 when
-#'     not using dispatcher.
 #' @param maxtasks [default Inf] the maximum number of tasks to execute (task
 #'     limit) before exiting.
 #' @param idletime [default Inf] maximum idle time, since completion of the last
@@ -45,6 +40,11 @@
 #' @param timerstart [default 0L] number of completed tasks after which to start
 #'     the timer for 'idletime' and 'walltime'. 0L implies timers are started
 #'     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).
 #' @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

@@ -21,10 +21,10 @@
 #' Set 'daemons' or persistent background processes receiving \code{\link{mirai}}
 #'     requests. These are by default created on the local machine.
 #'     Alternatively, for distributing tasks across the network, a host URL
-#'     may be specified to receive connections from remote daemons started with
-#'     \code{\link{daemon}}. Daemons may use either the dispatcher, which
-#'     ensures tasks are assigned to daemons efficiently on a FIFO basis, or
-#'     else the low-level approach of distributing tasks to daemons equally.
+#'     may be specified to receive connections from remote daemons. These may be
+#'     started using \code{\link{launch_remote}}. Daemons may use the dispatcher,
+#'     which ensures optimal FIFO scheduling, or else the low-level approach of
+#'     distributing tasks in a round-robin fashion.
 #'
 #' @inheritParams dispatcher
 #' @inheritDotParams dispatcher token:lock
@@ -33,7 +33,7 @@
 #' @param url [default NULL] if specified, the character URL or vector of URLs
 #'     on the host for remote daemons to dial into, including a port accepting
 #'     incoming connections (and optionally for websockets, a path), e.g.
-#'     'tcp://192.168.0.2:5555' or 'ws://192.168.0.2:5555/path'. Specify a URL
+#'     'tcp://10.75.32.70:5555' or 'ws://10.75.32.70:5555/path'. Specify a URL
 #'     starting 'tls+tcp://' or 'wss://' to use secure TLS connections.
 #' @param dispatcher [default TRUE] logical value whether to use dispatcher.
 #'     Dispatcher is a local background process that connects to daemons on
@@ -90,6 +90,17 @@
 #'     For historical reasons, \code{daemons()} with no arguments returns the
 #'     value of \code{\link{status}}.
 #'
+#' @section Local Daemons:
+#'
+#'     Daemons provide a potentially more efficient solution for asynchronous
+#'     operations as new processes no longer need to be created on an \emph{ad
+#'     hoc} basis.
+#'
+#'     Supply the argument 'n' to set the number of daemons. New background
+#'     \code{\link{daemon}} processes are automatically created on the local
+#'     machine connecting back to the host process, either directly or via
+#'     dispatcher.
+#'
 #' @section Dispatcher:
 #'
 #'     By default \code{dispatcher = TRUE}. This launches a background process
@@ -110,22 +121,11 @@
 #'     provides a resource-light approach suited to working with similar-length
 #'     tasks, or where concurrent tasks typically do not exceed available daemons.
 #'
-#' @section Local Daemons:
-#'
-#'     Daemons provide a potentially more efficient solution for asynchronous
-#'     operations as new processes no longer need to be created on an \emph{ad
-#'     hoc} basis.
-#'
-#'     Supply the argument 'n' to set the number of daemons. New background
-#'     \code{\link{daemon}} processes are automatically created on the local
-#'     machine connecting back to the host process, either directly or via a
-#'     dispatcher.
-#'
 #' @section Distributed Computing:
 #'
 #'     Specifying 'url' allows tasks to be distributed across the network.
 #'
-#'     The host URL should be a character string such as: 'tcp://192.168.0.2:5555'
+#'     The host URL should be a character string such as: 'tcp://10.75.32.70:5555'
 #'     at which daemon processes started using \code{\link{daemon}} should
 #'     connect to. The full shell command to deploy on remote machines may be
 #'     generated by \code{\link{launch_remote}}.
@@ -149,9 +149,9 @@
 #'     websocket URL supports a path after the port number, which can be made
 #'     unique for each daemon.
 #'
-#'     Specifying a single host URL such as 'ws://192.168.0.2:5555' with
+#'     Specifying a single host URL such as 'ws://10.75.32.70:5555' with
 #'     \code{n = 6} will automatically append a sequence to the path, listening
-#'     to the URLs 'ws://192.168.0.2:5555/1' through 'ws://192.168.0.2:5555/6'.
+#'     to the URLs 'ws://10.75.32.70:5555/1' through '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 'n' as this can
@@ -168,7 +168,7 @@
 #'
 #'     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 'n' specified e.g. the host URL 'tcp://192.168.0.2:5555' with
+#'     for 'n' specified e.g. the host URL 'tcp://10.75.32.70:5555' with
 #'     \code{n = 6} listens to the contiguous block of ports 5555 through 5560.
 #'
 #'     \strong{Without Dispatcher}
@@ -182,7 +182,8 @@
 #'
 #'     '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.
+#'     distributes tasks to all connected daemons and dispatchers in a round-robin
+#'     fashion.
 #'
 #' @section Compute Profiles:
 #'

R/dispatcher.R

@@ -25,10 +25,10 @@
 #' @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://192.168.0.2:5555' or 'ws://192.168.0.2:5555/path'.
+#'     e.g. 'tcp://10.75.32.70:5555' or 'ws://10.75.32.70:5555/path'.
 #' @param url (optional) the character URL or vector of URLs dispatcher should
 #'     listen at, including the port to connect to (and optionally for websockets,
-#'     a path), e.g. 'tcp://192.168.0.2:5555' or 'ws://192.168.0.2:5555/path'.
+#'     a path), e.g. 'tcp://10.75.32.70:5555' or 'ws://10.75.32.70:5555/path'.
 #'     Specify 'tls+tcp://' or 'wss://' to use secure TLS connections. Tasks are
 #'     sent to daemons dialled into these URLs. If not supplied, 'n' local
 #'     inter-process URLs will be assigned automatically.

R/launchers.R

@@ -23,9 +23,10 @@
 #'     re-launch daemons that have timed out on the local machine.
 #'
 #' @inheritParams saisei
+#' @inheritDotParams daemon asyncdial:output
 #' @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://192.168.0.2:5555' or 'ws://192.168.0.2:5555/path'
+#'     tcp://10.75.32.70: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).
@@ -42,24 +43,6 @@
 #'
 #' @return For \strong{launch_local}: Invisible NULL.
 #'
-#' @section Additional arguments:
-#'
-#'     Additional arguments may be specified as part of '\code{...}' to be
-#'     passed on to \code{\link{daemon}}:
-#'
-#'     \itemize{
-#'     \item{\strong{asyncdial}} {[default FALSE] whether to perform dials
-#'     asynchronously. The default FALSE will error if a connection is not
-#'     immediately possible (e.g. \code{\link{daemons}} has yet to be called, or
-#'     the specified port is not open etc.). Specifying TRUE continues retrying
-#'     (indefinitely) if not immediately successful, which is more resilient but
-#'     can mask potential connection issues.}
-#'     \item{\strong{output}} {[default FALSE] Specify as TRUE to provide
-#'     redirection of output (stdout and stderr) from the daemon to the host
-#'     process. This option is only applicable for local daemons when not using
-#'     dispatcher.}
-#'     }
-#'
 #' @details If daemons have been set, the generated command will automatically
 #'     contain the argument 'rs' specifying the length 7 L'Ecuyer-CMRG random
 #'     seed supplied to the daemon. The values will be different each time the

README.Rmd

@@ -100,8 +100,16 @@ Alternatively, explicitly call and wait for the result using `call_mirai()`.
 call_mirai(m)$data |> str()
 ```
 
+### Reference Vignette
 
-Refer to the ['reference'](https://shikokuchuo.net/mirai/articles/reference.html) vignette for the full package functionality, which includes launching daemons - persistent background processes on local or remote machines. This may be accessed within R by:
+See the [reference vignette](https://shikokuchuo.net/mirai/articles/reference.html) for the full package functionality, which includes the following key topics, amongst others:
+
+1. Example use cases
+2. Local daemons - persistent background processes
+3. Distributed computing - remote daemons
+4. Secure TLS connections
+
+This may be accessed within R by:
 
 ```{r vignette, eval=FALSE}
 vignette("reference", package = "mirai")

README.md

@@ -90,21 +90,29 @@ result.
 
 ``` r
 m$data |> str()
-#>  num [1:100000000] -1.163 -5.3031 -0.8701 2.7348 -0.0317 ...
+#>  num [1:100000000] 1.324 -1.279 0.366 1.537 1.423 ...
 ```
 
 Alternatively, explicitly call and wait for the result using
 `call_mirai()`.
 
 ``` r
 call_mirai(m)$data |> str()
-#>  num [1:100000000] -1.163 -5.3031 -0.8701 2.7348 -0.0317 ...
+#>  num [1:100000000] 1.324 -1.279 0.366 1.537 1.423 ...
 ```
 
-Refer to the
-[‘reference’](https://shikokuchuo.net/mirai/articles/reference.html)
-vignette for the full package functionality, which includes launching
-daemons - persistent background processes on local or remote machines.
+### Reference Vignette
+
+See the [reference
+vignette](https://shikokuchuo.net/mirai/articles/reference.html) for the
+full package functionality, which includes the following key topics,
+amongst others:
+
+1.  Example use cases
+2.  Local daemons - persistent background processes
+3.  Distributed computing - remote daemons
+4.  Secure TLS connections
+
 This may be accessed within R by:
 
 ``` r