Stable daemons() logical return value (#412)

* Change `daemons()` return value to logical

* Update news

* Tweak one

Author: shikokuchuo

NEWS.md

@@ -2,36 +2,35 @@
 
 #### Behavioural Changes
 
-* `daemons()` creating new daemons returns invisibly the character compute profile created.
-  `daemons(0)` or `daemons(NULL)` resetting daemons returns invisible NULL (thanks @eliocamp, #384).
-* Calling `daemons()` will now reset any existing daemons for the same compute profile rather than error.
-  This means that an explicit `daemons(0)` is no longer required before applying new settings (#383).
+* `daemons()` now returns invisibly logical `TRUE` when creating daemons and `FALSE` when resetting them, for simplicity and consistency (#384).
+* `daemons()` creating new daemons now resets any existing daemons for the compute profile rather than error.
+  This means that an explicit `daemons(0)` is no longer required before applying new settings (thanks @eliocamp, #383).
 
 #### New Features
 
-* New `with_daemons()` and `local_daemons()` helper functions for using a particular compute profile.
+* Adds `with_daemons()` and `local_daemons()` helper functions for using a particular compute profile.
   This works with daemons that are already set up unlike the existing `with.miraiDaemons()` method, which creates a new scope and tears it down when finished (#360).
-* Each mirai now has an attribute `id`, which is a monotonically increasing integer identifier in each session.
+* A mirai now has an attribute `id`, which is a monotonically increasing integer identifier unique to each session.
 
 #### Updates
 
-* Improved behaviour when using `serial_config()` custom serialization.
+* `miraiError` enhancements:
+  + Preserves the original condition classes and may be re-thrown as the original condition (thanks @sebffischer, #400).
+  + The print method includes the customary additional line break (thanks @sebffischer, #399).
+* Fixes `daemons(n)` failing to launch local daemons if mirai was installed in a custom user library set by an explicit `.libPaths()` call in '.Rprofile' (thanks @erydit and @dpastoor, #390).
+* Improved behaviour for `serial_config()` custom serialization.
   If the serialization hook function errors or otherwise fails to return a raw vector, this will error out rather than be silently ignored (thanks @dipterix, #378).
+* `as.promise()` method for mirai made robust for high-throughput scenarios (#377).
+* `mirai_map()` now supports Arrow Tables and Polars DataFrames (#366).
 * `require_daemons()` arguments are swapped so that `.compute` comes before `call` for ease of use.
   Previous usage will work for the time being, although is deprecated and will be defunct in a future version.
-* Fixes `daemons(n)` failing to launch local daemons if mirai was installed in a custom user library set by an explicit `.libPaths()` call in '.Rprofile' (thanks @erydit and @dpastoor, #390).
 * Enhancements to `everywhere()`:
   + Consecutive `everywhere()` calls are permissible again when using dispatcher (behaviour update in v2.4.1) (#354).
   + No longer has any effect on the RNG stream when using a reproducible `seed` value at `daemons()` (#356).
-* `mirai_map()` now supports Arrow Tables and Polars DataFrames (#366).
+* A `mirai()` evaluated on an ephemeral daemon returns invisibly, consistent with other cases (#351).
 * `daemon()` gains a `tlscert` argument for custom TLS certificates.
   The change in argument name lets this be passed when making a `daemons()` call (#344).
 * The `tls` argument at `daemon()`, `launch_local()` and `launch_remote()` is deprecated.
-* `as.promise()` method for mirai made robust for high-throughput scenarios (#377).
-* `miraiError` enhancements:
-  + Preserves the original condition classes and may be re-thrown as the original condition (thanks @sebffischer, #400).
-  + The print method includes the customary additional line break (thanks @sebffischer, #399).
-* A `mirai()` evaluated on an ephemeral daemon returns invisibly, consistent with other cases (#351).
 * Requires nanonext >= [1.6.2.9002].
 
 # mirai 2.4.1

R/daemons.R

@@ -72,8 +72,8 @@
 #'   `tls` is encrypted with a password) For security, should be provided
 #'   through a function that returns this value, rather than directly.
 #'
-#' @return Invisibly, the character compute profile created, or else NULL when
-#'   resetting daemons.
+#' @return Invisibly, logical `TRUE` when creating daemons and `FALSE` when
+#'   resetting.
 #'
 #' @section Local Daemons:
 #'
@@ -249,7 +249,7 @@ daemons <- function(
         launch_remote(n = n, remote = remote, .compute = .compute)
         on.exit()
       }
-      TRUE
+      url
     }
   } else {
     signal <- is.null(n)
@@ -258,12 +258,12 @@ daemons <- function(
     n <- as.integer(n)
 
     n == 0L && {
-      is.null(envir) && return(invisible())
+      is.null(envir) && return(invisible(FALSE))
 
       if (signal) send_signal(envir)
       reap(envir[["sock"]])
       ..[[.compute]] <- NULL -> envir
-      return(invisible())
+      return(invisible(FALSE))
     }
     res <- if (is.null(envir)) {
       n > 0L || stop(._[["n_zero"]])
@@ -282,7 +282,7 @@ daemons <- function(
   }
 
   is.null(res) && return({
-    daemons(0, .compute = .compute)
+    daemons(0L, .compute = .compute)
     daemons(
       n = n,
       url = url,
@@ -297,7 +297,7 @@ daemons <- function(
     )
   })
 
-  invisible(`class<-`(.compute, "miraiDaemons"))
+  invisible(`class<-`(TRUE, c("miraiDaemons", .compute)))
 }
 
 #' @export
@@ -336,7 +336,7 @@ print.miraiDaemons <- function(x, ...) print(unclass(x))
 #'
 with.miraiDaemons <- function(data, expr, ...) {
   prev_profile <- .[["cp"]]
-  `[[<-`(., "cp", data)
+  `[[<-`(., "cp", class(data)[2L])
   on.exit({
     daemons(0L)
     `[[<-`(., "cp", prev_profile)
@@ -445,7 +445,6 @@ require_daemons <- function(.compute = NULL, call = environment()) {
   daemons_set(.compute = .compute) || .[["require_daemons"]](.compute, call)
 }
 
-
 #' With Daemons
 #'
 #' Evaluate an expression using a specific compute profile.
@@ -459,19 +458,19 @@ require_daemons <- function(.compute = NULL, call = environment()) {
 #'   For **local_daemons**: invisible NULL.
 #'
 #' @examplesIf interactive()
-#' d1 <- daemons(1, dispatcher = FALSE, .compute = "cpu")
-#' d2 <- daemons(1, dispatcher = FALSE, .compute = "gpu")
+#' daemons(1, dispatcher = FALSE, .compute = "cpu")
+#' daemons(1, dispatcher = FALSE, .compute = "gpu")
 #'
-#' with_daemons(d1, {
+#' with_daemons("cpu", {
 #'   s1 <- status()
 #'   m1 <- mirai(Sys.getpid())
 #' })
 #'
-#' with_daemons(d2, {
+#' with_daemons("gpu", {
 #'   s2 <- status()
 #'   m2 <- mirai(Sys.getpid())
 #'   m3 <- mirai(Sys.getpid(), .compute = "cpu")
-#'   local_daemons(d1)
+#'   local_daemons("cpu")
 #'   m4 <- mirai(Sys.getpid())
 #' })
 #'

dev/vignettes/_mirai.Rmd

@@ -600,23 +600,23 @@ Similarly, functions such as `status()`, `launch_local()` or `launch_remote()` s
 
 #### `with_daemons()` and `local_daemons()`
 
-`daemons()` returns (invisibly) the compute profile of daemons created as a character string. Supplying this to `with_daemons()` or `local_daemons()` automatically sets the default compute profile of all package functions within the relevant scope.
+Supplying a character compute profile to `with_daemons()` or `local_daemons()` automatically sets the default compute profile for all package functions within the relevant scope.
 
 ```{r}
 #| label: withdaemons
-d1 <- daemons(1, .compute = "cpu")
-d2 <- daemons(1, .compute = "gpu")
+daemons(1, .compute = "cpu")
+daemons(1, .compute = "gpu")
 
-with_daemons(d1, {
+with_daemons("cpu", {
   s1 <- status()
   m1 <- mirai(Sys.getpid())
 })
 
-with_daemons(d2, {
+with_daemons("gpu", {
   s2 <- status()
   m2 <- mirai(Sys.getpid())
   m3 <- mirai(Sys.getpid(), .compute = "cpu")
-  local_daemons(d1)
+  local_daemons("cpu")
   m4 <- mirai(Sys.getpid())
 })
 
@@ -635,7 +635,7 @@ with_daemons("gpu", daemons(0))
 
 #### With Method
 
-`daemons()` also has a `with()` method, which evaluates an expression with daemons created for the duration of the expression and automatically torn down upon completion. All package functions within the `with()` scope default to using the compute profile of the daemons created.
+`daemons()` also has a `with()` method, which evaluates an expression with daemons created for the duration of the expression and automatically reset upon completion. All package functions within the `with()` scope default to using the compute profile of the daemons created.
 
 It was originally designed for running a Shiny app with the desired number of daemons, as in the example below:
 
@@ -651,4 +651,4 @@ with(daemons(4, .compute = "shiny"), shiny::runApp(app))
 Wrapping a call to `shiny::shinyApp()` would not work as `runApp()` is implicitly called when the app is printed, however printing occurs only after `with()` has returned, hence the app would run outside of the scope of the `with()` statement.
 
 In the case of a Shiny app, all mirai calls will be executed before the app returns as the app itself is blocking.
-In the case of other expressions, be sure to call or collect the values of all mirai within the expression to ensure that they all complete before the daemons are torn down.
+In the case of other expressions, be sure to call or collect the values of all mirai within the expression to ensure that they all complete before the daemons are reset.