Combining promises

Gathering

The most common pattern for combining promises is gathering, where you have two or more promises in hand and you want to use all of their results in a computation. The promise_all function is designed for this. Its signature looks like this:

promise_all(..., .list = NULL)

promise_all takes any number of promises as named arguments, and returns a promise of a list containing named elements with the results of those promises.

Here’s an example using promise_all to combine the results of two async read.csv operations:

library(promises)
library(future)
plan(multisession)

a <- future_promise(read.csv("a.csv"))
b <- future_promise(read.csv("b.csv"))

result <- promise_all(a = a, b = b) %...>% {
  rbind(.$a, .$b)
}

In this example, the value of . within the curly braces is a list whose elements a and b are both data frames. We use rbind to combine them.

The .$ prefix is a bit inelegant, so we recommend the use of the base R function with, which lets you skip the prefix. Here’s the same example, with with:

library(promises)
library(future)
plan(multisession)

a <- future_promise(read.csv("a.csv"))
b <- future_promise(read.csv("b.csv"))

promise_all(a = a, b = b) %...>%
  with({
    rbind(a, b)
  })

(Note that since the promise_all argument names are the same as the variable names (a = a, b = b), the original variables are masked: inside the with block, a now refers to the result of the promise a, not the promise object itself. If you find this confusing, you can just choose a different argument name, like promise_all(a_result = a, …).)

The combination of promise_all and with is a concise and powerful way to gather the results of multiple promises.

promise_all also gives you two other options for passing input promises. First, if you would rather your result list be unnamed, you can pass in promises as unnamed arguments: promise_all(a, b) would yield list(1, 2). Second, if you have a list of promises already in hand, you can pass the list as a single argument using promise_all(.list = x) (instead of, say, using do.call(promise_all, x)).

Nesting

Gathering is easy and convenient, but sometimes not flexible enough. For example, if you use the result of promise a to decide whether to launch a second async task, whose result you then use in combination with the result of a.

library(promises)
library(future)
plan(multisession)

a <- future_promise(1)

a %...>% (function(a) {
  b <- future_promise(2)
  b %...>% (function(b) {
    a + b
  })
})

(We use anonymous functions here to mask the names of the original promises–i.e. once inside the first anonymous function, the symbol a now refers to the result of the promise a.)

The nesting pattern is effective and flexible. The main downside is the physical nesting of the source code; if you use this pattern to a depth of more than a couple of promises, your code will be quite indented (in programming jargon this is referred to as the “pyramid of doom”).

Racing

library(promises)
library(future)
plan(multisession)

a <- future_promise({ Sys.sleep(1); 1 })
b <- future_promise({ Sys.sleep(0.5); 2 })

first <- promise_race(a, b)

promise_race takes multiple promises and returns a new promise that will be fulfilled with the first promise that succeeds. In the example above, first is a promise that will be fulfilled with 2 after 0.5 seconds.

If one of the input promises rejects before any succeed, then the returned promise will be rejected.

Note that promises does not currently support cancellation. So losing promises will attempt to run to completion even after the race ends.

Mapping

Use promise_map to run an async operation on each element of a list or vector, and collect the results in a list. It’s very similar to lapply or purrr::map, except that the function to apply can return a promise, and the return value is also a promise.

In the example below, we iterate over a named vector of package names. For each package name, we launch an async task to download the package’s description file from CRAN pick out the last published date.

library(promises)
library(future)
plan(multisession)

get_pub_date <- function(pkg) {
  desc_url <- paste0("https://cran.r-project.org/web/packages/", pkg, "/DESCRIPTION")
  future_promise({
    read.dcf(url(desc_url))[, "Date/Publication"] %>% unname()
  })
}

packages <- setNames(, c("ggplot2", "dplyr", "knitr"))

pkg_dates <- promise_map(packages, get_pub_date)

pkg_dates %...>% print()

The resulting output looks like this:

$ggplot2
[1] "2016-12-30 22:45:17"

$dplyr
[1] "2017-09-28 20:43:29 UTC"

$knitr
[1] "2018-01-29 11:01:22 UTC"

promise_map works serially; each time it calls the given function on an element of the list/vector, it will wait for the returned promise to resolve before proceeding to the next element. Furthermore, any error or rejected promise will cause the entire promise_map operation to reject.

If you want behavior that’s similar to promise_map but for all the async operations to occur in parallel, you can achieve that with a combination of a regular purrr::map and promise_all:

pkg_dates <- purrr::map(packages, get_pub_date) %>%
  promise_all(.list = .)

pkg_dates %...>% print()

Reducing

Use promise_reduce when you have a list where you want to run an async operation on each of the elements, and to do so serially (i.e. only one async operation runs at a time). This can be helpful when you’re searching through some elements using an async operation and want to terminate early when your search succeeds.

The signature of promise_reduce is as follows:

promise_reduce(x, func, init = NULL)

If you’ve worked with base::Reduce() or purr:::reduce(), this should seem reasonably familiar: x is a vector or list; func is a function that takes two arguments, the accumulated value and the “next” value; and init is the default accumulated value.

The main difference between promise_reduce and purrr:::reduce is that with promise_reduce, your func can return a promise. If it does, promise_reduce will wait for it to resolve before updating the accumulated value and invoking func on the next element. The result returned from promise_reduce is a promise that resolves to the ultimate accumulated value.

The following example loops through a partial list of CRAN mirrors, returning the first one that passes whatever check http::http_error performs.

library(promises)
library(future)
plan(multisession)

cran_mirrors <- c(
  "https://cloud.r-project.org",
  "https://cran.usthb.dz",
  "https://cran.csiro.au",
  "https://cran.wu.ac.at"
)

promise_reduce(cran_mirrors, function(result, mirror) {
  if (!is.null(result)) {
    result
  } else {
    future_promise({
      # Test the URL; return the URL on success, or NULL on failure
      if (!httr::http_error(mirror)) mirror
    })
  }
}, .init = NULL) %...>% print()