crew_options_local()

NAMESPACE

@@ -27,6 +27,7 @@ export(crew_eval_async)
 export(crew_launcher)
 export(crew_launcher_local)
 export(crew_monitor_local)
+export(crew_options_local)
 export(crew_options_validate)
 export(crew_random_name)
 export(crew_relay)

R/crew_controller_local.R

@@ -38,8 +38,9 @@ crew_controller_local <- function(
   garbage_collection = FALSE,
   launch_max = 5L,
   r_arguments = c("--no-save", "--no-restore"),
+  options_local = crew::crew_options_local(),
   local_log_directory = NULL,
-  local_log_join = TRUE
+  local_log_join = NULL
 ) {
   crew_deprecate(
     name = "seconds_exit",
@@ -49,6 +50,26 @@ crew_controller_local <- function(
     condition = "warning",
     value = seconds_exit
   )
+  crew_deprecate(
+    name = "local_log_directory",
+    date = "2024-10-8",
+    version = "0.9.5.9012",
+    alternative = "options_local argument",
+    condition = "warning",
+    value = local_log_directory
+  )
+  crew_deprecate(
+    name = "local_log_join",
+    date = "2024-10-8",
+    version = "0.9.5.9012",
+    alternative = "options_local argument",
+    condition = "warning",
+    value = local_log_join
+  )
+  options_local$log_directory <- local_log_directory %|||%
+    options_local$log_directory
+  options_local$log_join <- local_log_join %|||%
+    options_local$log_join
   client <- crew_client(
     name = name,
     workers = workers,
@@ -77,6 +98,7 @@ crew_controller_local <- function(
     launch_max = launch_max,
     tls = tls,
     r_arguments = r_arguments,
+    options_local = options_local,
     local_log_directory = local_log_directory,
     local_log_join = local_log_join
   )

R/crew_launcher_local.R

@@ -4,17 +4,12 @@
 #' @description Create an `R6` object to launch and maintain
 #'   local process workers.
 #' @inheritParams crew_launcher
-#' @param local_log_directory Either `NULL` or a character of length 1
-#'   with the file path to a directory to write worker-specific log files
-#'   with standard output and standard error messages.
-#'   Each log file represents a single *instance* of a running worker,
-#'   so there will be more log files
-#'   if a given worker starts and terminates a lot. Set to `NULL` to suppress
-#'   log files (default).
-#' @param local_log_join Logical of length 1. If `TRUE`, `crew` will write
-#'   standard output and standard error to the same log file for
-#'   each worker instance. If `FALSE`, then they these two streams
-#'   will go to different log files with informative suffixes.
+#' @param options_local An object generated by [crew_options_local()]
+#'   with options specific to the local controller.
+#' @param local_log_directory Deprecated on 2024-10-08. Use
+#'   `options_local` instead.
+#' @param local_log_join Deprecated on 2024-10-08. Use
+#'   `options_local` instead.
 #' @examples
 #' if (identical(Sys.getenv("CREW_EXAMPLES"), "true")) {
 #' client <- crew_client()
@@ -44,8 +39,9 @@ crew_launcher_local <- function(
   launch_max = 5L,
   tls = crew::crew_tls(),
   r_arguments = c("--no-save", "--no-restore"),
+  options_local = crew::crew_options_local(),
   local_log_directory = NULL,
-  local_log_join = TRUE
+  local_log_join = NULL
 ) {
   crew_deprecate(
     name = "seconds_exit",
@@ -55,6 +51,26 @@ crew_launcher_local <- function(
     condition = "warning",
     value = seconds_exit
   )
+  crew_deprecate(
+    name = "local_log_directory",
+    date = "2024-10-8",
+    version = "0.9.5.9012",
+    alternative = "options_local argument",
+    condition = "warning",
+    value = local_log_directory
+  )
+  crew_deprecate(
+    name = "local_log_join",
+    date = "2024-10-8",
+    version = "0.9.5.9012",
+    alternative = "options_local argument",
+    condition = "warning",
+    value = local_log_join
+  )
+  options_local$log_directory <- local_log_directory %|||%
+    options_local$log_directory
+  options_local$log_join <- local_log_join %|||%
+    options_local$log_join
   name <- as.character(name %|||% crew_random_name())
   launcher <- crew_class_launcher_local$new(
     name = name,
@@ -72,8 +88,7 @@ crew_launcher_local <- function(
     launch_max = launch_max,
     tls = tls,
     r_arguments = r_arguments,
-    local_log_directory = local_log_directory,
-    local_log_join = local_log_join
+    options_local = options_local
   )
   launcher$validate()
   launcher
@@ -101,43 +116,38 @@ crew_class_launcher_local <- R6::R6Class(
   inherit = crew_class_launcher,
   cloneable = FALSE,
   private = list(
-    .local_log_directory = NULL,
-    .local_log_join = NULL,
+    .options_local = NULL,
     .log_prepare = function() {
-      if (!is.null(private$.local_log_directory)) {
-        dir_create(private$.local_log_directory)
+      if (!is.null(private$.options_local$log_directory)) {
+        dir_create(private$.options_local$log_directory)
       }
     },
     .log_stdout = function(name) {
-      directory <- private$.local_log_directory
+      directory <- private$.options_local$log_directory
       if (is.null(directory)) {
         return(NULL)
       }
-      if (!private$.local_log_join) {
+      if (!private$.options_local$log_join) {
         name <- paste0(name, "-stdout")
       }
       path.expand(file.path(directory, paste0(name, ".log")))
     },
     .log_stderr = function(name) {
-      directory <- private$.local_log_directory
+      directory <- private$.options_local$log_directory
       if (is.null(directory)) {
         return(NULL)
       }
       if_any(
-        private$.local_log_join,
+        private$.options_local$log_join,
         "2>&1",
         path.expand(file.path(directory, paste0(name, "-stderr.log")))
       )
     }
   ),
   active = list(
-    #' @field local_log_directory See [crew_launcher_local()].
-    local_log_directory = function() {
-      .subset2(private, ".local_log_directory")
-    },
-    #' @field local_log_join See [crew_launcher_local()].
-    local_log_join = function() {
-      .subset2(private, ".local_log_join")
+    #' @field options_local See [crew_launcher_local()].
+    options_local = function() {
+      .subset2(private, ".options_local")
     }
   ),
   public = list(
@@ -160,8 +170,7 @@ crew_class_launcher_local <- R6::R6Class(
     #' @param tls See [crew_launcher()].
     #' @param processes See [crew_launcher()].
     #' @param r_arguments See [crew_launcher()].
-    #' @param local_log_directory See [crew_launcher_local()].
-    #' @param local_log_join See [crew_launcher_local()].
+    #' @param options_local See [crew_launcher_local()].
     #' @examples
     #' if (identical(Sys.getenv("CREW_EXAMPLES"), "true")) {
     #' client <- crew_client()
@@ -192,8 +201,7 @@ crew_class_launcher_local <- R6::R6Class(
       tls = NULL,
       processes = NULL,
       r_arguments = NULL,
-      local_log_directory = NULL,
-      local_log_join = NULL
+      options_local = NULL
     ) {
       super$initialize(
         name = name,
@@ -214,26 +222,13 @@ crew_class_launcher_local <- R6::R6Class(
         processes = processes,
         r_arguments = r_arguments
       )
-      private$.local_log_directory <- local_log_directory
-      private$.local_log_join <- local_log_join
+      private$.options_local <- options_local
     },
     #' @description Validate the local launcher.
     #' @return `NULL` (invisibly).
     validate = function() {
       super$validate()
-      crew_assert(
-        private$.local_log_directory %|||% "x",
-        is.character(.),
-        length(.) == 1L,
-        !anyNA(.),
-        nzchar(.),
-        message = "local_log_directory must be NULL or a valid directory path."
-      )
-      crew_assert(
-        private$.local_log_join,
-        isTRUE(.) || isFALSE(.),
-        message = "local_log_join must be TRUE or FALSE."
-      )
+      crew_options_validate(private$.options_local)
     },
     #' @description Launch a local process worker which will
     #'   dial into a socket.

R/crew_options.R

@@ -1,6 +1,6 @@
 #' @title Validate options.
 #' @export
-#' @family utilities
+#' @family options
 #' @description Validate a `crew` options list.
 #' @return `NULL` (invisibly) on success, throws an error if there is
 #'   something wrong with the options list.

R/crew_options_local.R

@@ -1,4 +1,7 @@
-#' @title Local crew controller options.
+#' @title Local `crew` launcher options.
+#' @export
+#' @family options
+#' @description Options for the local `crew` launcher.
 #' @param log_directory Either `NULL` or a character of length 1
 #'   with the file path to a directory to write worker-specific log files
 #'   with standard output and standard error messages.

_pkgdown.yml

@@ -51,6 +51,7 @@ reference:
   contents:
   - crew_options_local
   - crew_options_metrics
+  - crew_options_validate
 - title: TLS configuration
   contents:
   - crew_tls
@@ -73,7 +74,6 @@ reference:
   - crew_clean
   - crew_deprecate
   - crew_eval
-  - crew_options_validate
   - crew_random_name
   - crew_retry
   - crew_terminate_process