tar_dispatched()

DESCRIPTION

@@ -12,7 +12,7 @@ Description: Pipeline tools coordinate the pieces of computationally
   The methodology in this package
   borrows from GNU 'Make' (2015, ISBN:978-9881443519)
   and 'drake' (2018, <doi:10.21105/joss.00550>).
-Version: 1.3.2.9003
+Version: 1.3.2.9004
 License: MIT + file LICENSE
 URL: https://docs.ropensci.org/targets/, https://github.com/ropensci/targets
 BugReports: https://github.com/ropensci/targets/issues

NAMESPACE

@@ -389,6 +389,7 @@ export(tar_deps)
 export(tar_deps_raw)
 export(tar_destroy)
 export(tar_dir)
+export(tar_dispatched)
 export(tar_edit)
 export(tar_engine_knitr)
 export(tar_envir)

NEWS.md

@@ -1,4 +1,4 @@
-# targets 1.3.2.9003 (development)
+# targets 1.3.2.9004 (development)
 
 ## Invalidating changes
 
@@ -27,6 +27,9 @@ Because of the changes below, upgrading to this version of `targets` will unavoi
 ## Other changes
 
 * Migrate to the changes in `clustermq` 0.9.0 (@mschubert).
+* In progress statuses, change "started" to "dispatched" and change "built" to "completed" (#1182).
+* Deprecate `tar_started()` in favor of `tar_dispatched()` (#1182).
+* Deprecate `tar_built()` in favor of `tar_completed()` (#1182).
 
 # targets 1.3.2
 

R/tar_dispatched.R

@@ -0,0 +1,42 @@
+#' @title List dispatched targets.
+#' @export
+#' @family progress
+#' @description List the targets with progress status `"dispatched"`.
+#' @details A target is `"dispatched"` if it is sent off to be run. Depending
+#'   on your high-performance computing configuration via the `crew` package,
+#'   the may not actually start right away. This may happen if the target
+#'   is ready to start but all available parallel workers are busy.
+#' @return A character vector of dispatched targets.
+#' @inheritParams tar_progress
+#' @param names Optional, names of the targets. If supplied, the
+#'   function restricts its output to these targets.
+#'   You can supply symbols
+#'   or `tidyselect` helpers like [any_of()] and [starts_with()].
+#' @examples
+#' if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
+#' tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
+#' tar_script({
+#'   list(
+#'     tar_target(x, seq_len(2)),
+#'     tar_target(y, 2 * x, pattern = map(x))
+#'   )
+#' }, ask = FALSE)
+#' tar_make()
+#' tar_dispatched()
+#' tar_dispatched(starts_with("y_")) # see also any_of()
+#' })
+#' }
+tar_dispatched <- function(
+  names = NULL,
+  store = targets::tar_config_get("store")
+) {
+  tar_assert_allow_meta("tar_dispatched", store)
+  progress <- progress_init(path_store = store)
+  progress <- tibble::as_tibble(progress$database$read_condensed_data())
+  names_quosure <- rlang::enquo(names)
+  names <- tar_tidyselect_eval(names_quosure, progress$name)
+  if (!is.null(names)) {
+    progress <- progress[match(names, progress$name), , drop = FALSE] # nolint
+  }
+  progress$name[progress$progress == "dispatched"]
+}

R/tar_started.R

@@ -1,7 +1,8 @@
-#' @title List started targets.
+#' @title Deprecated: list started targets.
 #' @export
-#' @family progress
-#' @description List targets whose progress is `"started"`.
+#' @keywords internal
+#' @description Deprecated in favor of [tar_dispatched()] on 2023-12-04
+#'   (version 1.3.2.9004).
 #' @return A character vector of started targets.
 #' @inheritParams tar_progress
 #' @param names Optional, names of the targets. If supplied, the
@@ -18,14 +19,18 @@
 #'   )
 #' }, ask = FALSE)
 #' tar_make()
-#' tar_started()
-#' tar_started(starts_with("y_")) # see also any_of()
+#' tar_dispatched()
+#' tar_dispatched(starts_with("y_")) # see also any_of()
 #' })
 #' }
 tar_started <- function(
   names = NULL,
   store = targets::tar_config_get("store")
 ) {
+  tar_warn_deprecate(
+    "tar_started() is deprecated in targets version >= 1.3.2.9004 ",
+    "(2021-12-04). Use tar_dispatched() instead."
+  )
   tar_assert_allow_meta("tar_started", store)
   progress <- progress_init(path_store = store)
   progress <- tibble::as_tibble(progress$database$read_condensed_data())
@@ -34,5 +39,5 @@ tar_started <- function(
   if (!is.null(names)) {
     progress <- progress[match(names, progress$name), , drop = FALSE] # nolint
   }
-  progress$name[progress$progress == "started"]
+  progress$name[progress$progress == "dispatched"]
 }

_pkgdown.yml

@@ -111,11 +111,11 @@ reference:
   - '`tar_progress`'
   - '`tar_progress_branches`'
   - '`tar_progress_summary`'
-  - '`tar_built`'
+  - '`tar_skipped`'
+  - '`tar_dispatched`'
+  - '`tar_completed`'
   - '`tar_canceled`'
   - '`tar_errored`'
-  - '`tar_skipped`'
-  - '`tar_started`'
 - title: Time
   contents:
   - '`tar_newer`'