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. -
oncestores 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.
