resolved(): consolidate and improve documentation

Author: HenrikBengtsson

DESCRIPTION

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

R/backend_api-11.ClusterFutureBackend-class.R

@@ -545,6 +545,26 @@ getSocketSelectTimeout <- function(future, timeout = NULL) {
 } ## getSocketSelectTimeout()
 
 
+#' @param timeout (numeric) The maximum time (in seconds) for polling the worker
+#' for a response. If no response is available within this time limit, FALSE is
+#' returned assuming the future is still being processed.
+#' If NULL, the value defaults to `getOption("future.<type>.resolved.timeout")`,
+#' then `getOption("future.resolved.timeout")`, and finally 0.01 (seconds),
+#' where `<type>` corresponds to the type of future, e.g. `cluster` and `multicore`.
+#'
+#' @section Behavior of cluster and multisession futures:
+#' `resolved()` for `ClusterFuture`, and therefore also `MultisessionFuture`,
+#' will always check whether any of the currently running futures are resolved,
+#' and if one of them has been resolved, then its result is collected. This makes
+#' sure to free up workers, when possible.
+#'
+#' `resolved()` for `ClusterFuture` may receive immediate condition objects, rather
+#' than a [FutureResult], when polling the worker for results. In such cases, the
+#' condition object is collected and another poll it performed. Up to 100 immediate
+#' conditions may be collected this way per `resolved()` call, before considering
+#' the future non-resolved and FALSE being returned.
+#'
+#' @rdname resolved
 #' @importFrom parallelly connectionId isConnectionValid
 #' @export
 resolved.ClusterFuture <- function(x, run = TRUE, timeout = NULL, ...) {
@@ -585,7 +605,8 @@ resolved.ClusterFuture <- function(x, run = TRUE, timeout = NULL, ...) {
 
       ## If at least one is available, then launch this lazy future
       if (any(avail)) future <- run(future)
-    }
+    } ## if (run)
+    
     return(FALSE)
   }
 
@@ -1568,15 +1589,15 @@ handleInterruptedFuture <- local({
 #' If a function, it is called without arguments _when the future
 #' is created_ and its value is used to configure the workers.
 #' The function should return any of the above types.
+#' If `workers == 1`, then all processing using done in the
+#' current/main \R session and we therefore fall back to using a
+#' sequential future. To override this fallback, use `workers = I(1)`.
 #'
 #' @param persistent If FALSE, the evaluation environment is cleared
 #' from objects prior to the evaluation of the future.
 #' 
 #' @param \ldots Additional named elements passed to [Future()].
 #'
-#' @return
-#' A ClusterFuture.
-#'
 #' @example incl/cluster.R
 #'
 #' @seealso

R/backend_api-11.MulticoreFutureBackend-class.R

@@ -271,19 +271,11 @@ nbrOfFreeWorkers.MulticoreFutureBackend <- function(evaluator, background = FALS
 
 
 
-#' A multicore future is a future whose value will be resolved asynchronously in a parallel process
-#'
-#' @inheritParams MultiprocessFuture-class
-#' @inheritParams Future-class
-#'
-#' @return
-#' `MulticoreFuture()` returns an object of class `MulticoreFuture`.
-#'
-#' @section Usage:
-#' To use 'multicore' futures, use `plan(multicore, ...)`, cf. [multicore].
-#'
-#' @name MulticoreFuture-class
-#' @keywords internal
+#' @section Behavior of multicore futures:
+#' `resolved()` for `MulticoreFuture` may receive immediate condition objects, rather than a
+#' [FutureResult], when polling the worker for results. In such cases, _all_ such condition
+#' objects are collected, before considering the future non-resolved and FALSE being returned.
+#' @rdname resolved
 #' @export
 resolved.MulticoreFuture <- local({
   selectChildren <- import_parallel_fcn("selectChildren")
@@ -618,16 +610,11 @@ interruptFuture.MulticoreFutureBackend <- function(backend, future, ...) {
 #' @param workers The number of parallel processes to use.
 #' If a function, it is called without arguments _when the future
 #' is created_ and its value is used to configure the workers.
-#'
-#' @param \ldots Additional named elements to [Future()].
-#'
-#' @return
-#' A [Future].
 #' If `workers == 1`, then all processing using done in the
 #' current/main \R session and we therefore fall back to using a
 #' sequential future. To override this fallback, use `workers = I(1)`.
-#' This is also the case whenever multicore processing is not supported,
-#' e.g. on Windows.
+#'
+#' @param \ldots Additional named elements to [Future()].
 #'
 #' @example incl/multicore.R
 #'
@@ -665,6 +652,7 @@ interruptFuture.MulticoreFutureBackend <- function(backend, future, ...) {
 #' whether multicore futures are supported or not on the current
 #' system.
 #'
+#' @aliases MulticoreFuture
 #' @export
 multicore <- function(..., workers = availableCores(constraints = "multicore"), gc = FALSE, earlySignal = FALSE, envir = parent.frame()) {
   stop("INTERNAL ERROR: The future::multicore() function must never be called directly")

R/backend_api-13.MultisessionFutureBackend-class.R

@@ -127,6 +127,7 @@ print.MultisessionFutureBackend <- function(x, validate = TRUE, ...) {
 #' Use [parallelly::availableCores()] to see the total number of
 #' cores that are available for the current \R session.
 #'
+#' @aliases MultisessionFuture
 #' @export
 multisession <- function(..., workers = availableCores(), lazy = FALSE, rscript_libs = .libPaths(), gc = FALSE, earlySignal = FALSE, envir = parent.frame()) {
   stop("INTERNAL ERROR: The future::multisession() must never be called directly")

R/backend_api-Future-class.R

@@ -722,6 +722,7 @@ result.Future <- function(future, ...) {
 }
 
 
+#' @rdname resolved
 #' @export
 resolved.Future <- function(x, run = TRUE, ...) {
   future <- x

R/core_api-resolved.R

@@ -3,20 +3,28 @@
 #' @param x A \link{Future}, a list, or an environment (which also
 #' includes \link[listenv:listenv]{list environment}).
 #'
+#' @param run (logical) If TRUE, any lazy futures is launched,
+#' otherwise not.
+#'
 #' @param \ldots Not used.
 #'
-#' @return A logical of the same length and dimensions as `x`.
+#' @return
+#' A logical vector of the same length and dimensions as `x`.
 #' Each element is TRUE unless the corresponding element is a
 #' non-resolved future in case it is FALSE.
 #'
 #' @details
-#' This method needs to be implemented by the class that implement
-#' the Future API.  The implementation should return either TRUE or FALSE
-#' and must never throw an error (except for [FutureError]:s which indicate
-#' significant, often unrecoverable infrastructure problems).
-#' It should also be possible to use the method for polling the
-#' future until it is resolved (without having to wait infinitely long),
-#' e.g. `while (!resolved(future)) Sys.sleep(5)`.
+#' Checking a lazy future, triggers it to be launched, unless `run = FALSE`.
+#'
+#' `resolved()` methods must always return `TRUE` or `FALSE` values, must
+#' always launch lazy futures by default (`run = TRUE`), and must never block
+#' indefinitely. This is because it should always be possible to poll futures
+#' until they are resolved using `resolved()`, e.g.
+#' `while (!all(resolved(futures))) Sys.sleep(5)`.
+#'
+#' Each future backend must implement a `resolved()` method that returns
+#' either TRUE or FALSE, or throw a [FutureError] (which indicate a
+#' significant, often unrecoverable infrastructure problem, or an interrupt).
 #'
 #' @export
 resolved <- function(x, ...) {
@@ -37,9 +45,15 @@ resolved <- function(x, ...) {
   UseMethod("resolved")
 }
 
+#' @return
+#' The default method always returns TRUE.
+#'
+#' @rdname resolved
 #' @export
 resolved.default <- function(x, ...) TRUE
 
+
+#' @rdname resolved
 #' @export
 resolved.list <- function(x, ...) {
   debug <- isTRUE(getOption("future.debug"))
@@ -76,6 +90,8 @@ resolved.list <- function(x, ...) {
   res
 }
 
+
+#' @rdname resolved
 #' @export
 resolved.environment <- function(x, ...) {
   debug <- isTRUE(getOption("future.debug"))