* print() on a Future outpus a description of the current state

* Using state = "failed" for more backends

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: future
-Version: 1.68.0-9004
+Version: 1.68.0-9005
 Title: Unified Parallel and Distributed Processing in R for Everyone
 Depends:
     R (>= 3.2.0)

NEWS.md

@@ -9,6 +9,8 @@
    which session (including UUID, hostname, and PID) and when the
    condition was created.
 
+ * `print()` on a Future outpus a description of the current state.
+
 ## Bug Fixes
 
  * `plan(..., interrupts = ...)` would produce a warning on "Detected

R/backend_api-11.MulticoreFutureBackend-class.R

@@ -480,7 +480,7 @@ result.MulticoreFuture <- local({
         future[["state"]] <- "interrupted"
       } else if (inherits(result, "FutureLaunchError")) {
         ex <- result
-        future[["state"]] <- "interrupted"
+        future[["state"]] <- "failed"
       } else if (inherits(result, "FutureError")) {
         ## FIXME: Add more details
         hint <- sprintf("parallel::mccollect() did return a FutureResult but a %s object: %s", sQuote(class(result)[1]), paste(deparse(result), collapse = "; "))

R/backend_api-11.SequentialFutureBackend-class.R

@@ -50,8 +50,13 @@ launchFuture.SequentialFutureBackend <- function(backend, future, ...) {
 
   ## Launch future
   future[["state"]] <- "running"
-  future[["result"]] <- evalFuture(data)
-  future[["state"]] <- "finished"
+  result <- evalFuture(data)
+  if (inherits(result, "FutureLaunchError")) {
+    future[["state"]] <- "failed"
+  } else {
+    future[["state"]] <- "finished"
+  }
+  future[["result"]] <- result
 
   ## Register run (used to collect statistics)
   reg <- backend[["reg"]]

R/backend_api-Future-class.R

@@ -337,10 +337,55 @@ print.Future <- function(x, ...) {
   cat(sprintf("Early signaling: %s\n", isTRUE(future[["earlySignal"]])))
   cat(sprintf("Environment: %s\n", envname(future[["envir"]])))
 
+  result <- future[["result"]]
   state <- future[["state"]]
-  cat(sprintf("State: %s\n", commaq(state)))
+  description <- switch(state,
+    created = {
+      "Future was created, but is yet to be submitted"
+    },
+    submitted = {
+      "Future has been submitted, but it is not known if it has been started"
+    },
+    running = {
+      "Future is being evaluated"
+    },
+    finished = {
+      stop_if_not(inherits(result, "FutureResult"))
+      conditions <- result[["conditions"]]
+      n <- length(conditions)
+      if (n == 0L) {
+        cond <- NULL
+      } else {
+        condition <- conditions[[n]]
+        cond <- condition[["condition"]]
+      }
+      if (inherits(cond, "error")) {
+        if (inherits(cond, "FutureInterruptError")) {
+          sprintf("Future was interrupted during evaluation, resulting in a %s", sQuote(class(cond)[1]))
+        } else if (inherits(cond, "FutureError")) {
+          sprintf("Future was resolved, but produced a %s", sQuote(class(cond)[1]))
+        } else {
+          "Future was resolved, but produced a run-time error"
+        }
+      } else if (inherits(cond, "interrupt")) {
+        "Future was interrupted during evaluation"
+      } else {
+        "Future was resolved successfully"
+      }
+    },
+    interrupted = {
+      "Future was interrupted during evaluation"
+    },
+    canceled = {
+      "Future was canceled"
+    },
+    failed = {
+      "Future failed due to an unexpected, internal error during launch, evaluation, or while returning the results"
+    },
+    NA_character_
+  )
+  cat(sprintf("State: %s (\"%s\")\n", commaq(state), description))
 
-  result <- future[["result"]]
   hasResult <- inherits(result, "FutureResult")
   ## BACKWARD COMPATIBILITY
   hasResult <- hasResult || exists("value", envir = future, inherits = FALSE)
@@ -477,16 +522,18 @@ run.Future <- function(future, ...) {
     if (debug) mdebug_push("Launching futures ...")
     future[["backend"]] <- backend
     future[["start"]] <- proc.time()[[3]]
-    future2 <- tryCatch(
+    future2 <- tryCatch({
       launchFuture(backend, future = future)
-    , FutureError = function(ex) {
+    }, FutureError = function(ex) {
+      future[["state"]] <- "failed"
       ## Known error caught by the future backend
       stop(ex)
     }, error = function(ex) {
       ## Unexpected error
       msg <- conditionMessage(ex)
       label <- sQuoteLabel(future)
       msg <- sprintf("Caught an unexpected error of class %s when trying to launch future (%s) on backend of class %s. The reason was: %s", class(ex)[1], label, class(backend)[1], msg)
+      future[["state"]] <- "failed"
       stop(FutureLaunchError(msg, future = future))
     })
     if (debug) mdebug_pop()
@@ -861,6 +908,48 @@ getExpression.Future <- local({
 }) ## getExpression()
 
 
+# Future states:
+#
+#  1. `created`:
+#     The future has been created, but not yet been submitted.
+#     Examples:
+#       A future created with `lazy = TRUE` is in this state.
+#
+#  2. `submitted`:
+#     The future has been submitted for evaluation.
+#     There is no evidence yet that the future is being evaluated.
+#     Examples:
+#       A future submitted to a queue may be in this state.
+#                
+#  3. `running`:
+#     The future is currently being evaluated.
+#     There is no evidence yet that the evaluation of the future has finished.
+#     Examples:
+#       Future being processed by a worker is typically in this state.
+#                
+#  4. `finished`:
+#     The evaluation of the future has completed.
+#     Examples:
+#       A future submitted to a queue may be in this state.
+#
+#  5. `failed`:
+#     The evaluation of the future has terminated, but failed before being
+#     completed.
+#     Examples:
+#       A future that failed to launch.
+#       An internal error occured while evaluating the future.
+#       An internal error occured after finishing future evaluation, but
+#       before return the results.
+#
+#  6. `interrupted`:
+#     The evaluation of the future has terminated, but was interrupted before
+#     being completed.
+#     Examples:
+#
+#  7. `canceled`:
+#     The evaluation of the future has terminated, but was canceled.
+#     Examples:
+#
 #' @export
 `$<-.Future` <- function(x, name, value) {
   if (name == "state") {