Skip to contents

Most decorators wait by blocking: retry() sleeps and rate_limit() sleeps. That is fine in a script, but it freezes a Shiny app or a plumber API. For functions that return a promise, each decorator has an async_ version that waits with later instead, and always returns a promise.

Blocking Asynchronous
retry() async_retry()
timeout() async_timeout()
circuit_breaker() async_circuit_breaker()
rate_limit() async_rate_limit()
fallback() async_fallback()
lru_cache(), cache, disk_cache() async_lru_cache(), async_cache, async_disk_cache()
once async_once
log_call() async_log_call()
validate_return() async_validate_return()

validate_args() works for both, because arguments are known when the function is called. contextmanager has no async version: its cleanup runs when a function exits, which for a promise is before the work is done.

Why not the blocking version?

The blocking versions look at the function, not its promise, so they see the wrong thing:

  • log_call() logs the finish when the promise is returned, not when it settles.
  • validate_return() checks the promise object, not the value it resolves to.
  • timeout() cannot bound work that happens after the function has returned.
  • once stores a rejected promise, so every later call fails.

The async_ versions follow the promise, so a rejection is a failure, and the value that is cached, validated or logged is the one it resolves to.

Stacking

The stacking order is the same as for the blocking versions, see vignette("decorators"). Put async_retry() outermost of the ones that wait, and cap each attempt with async_timeout() inside it.

n <- 0
fetch := async_fallback(value = "default") %@%
  async_retry(stop = stop_after_attempt(3), wait = wait_fixed(0.05)) %@%
  async_timeout(1) %@%
  function(url) {
    n <<- n + 1
    if (n < 3) stop("not yet")
    paste("response from", url)
  }

promises::then(fetch("example.com"), function(value) cat(value, "\n"))

# Shiny and plumber run the event loop for you. In a script, run it yourself.
while (!later::loop_empty()) {
  later::run_now(0.1)
}
## response from example.com

All of them need the promises package, and the ones that schedule work also need later. Both are only suggested by fnware, so you are told which to install the first time you use an async_ decorator.