--- title: "Asynchronous decorators" output: litedown::html_format vignette: > %\VignetteIndexEntry{Asynchronous decorators} %\VignetteEngine{litedown::vignette} %\VignetteEncoding{UTF-8} --- ```{r setup} library(fnware) ``` 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](https://rstudio.github.io/promises/), 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. ```{r stack, eval = requireNamespace("promises", quietly = TRUE) && requireNamespace("later", quietly = TRUE)} 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) } ``` 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.