Skip to contents

Which decorator do I want?

The problem Decorator Guide
A call fails now and then retry() vignette("retry")
A call hangs timeout() vignette("retry")
A service is down and callers keep waiting on it circuit_breaker() vignette("circuitbreaker")
An API allows only so many calls rate_limit() ?rate_limit
A failure should become a default value fallback() vignette("fallback")
A result is slow to compute and gets asked for again lru_cache(), cache, disk_cache() vignette("caching")
Setup should happen a single time once vignette("fallback")
You want to see what is being called log_call() vignette("logging")
Bad input or output should be caught early validate_args(), validate_return() vignette("validation")
Setup and teardown around a resource contextmanager vignette("contextmanager")

For a function that returns a promise, every decorator above except contextmanager has an async_ version. See vignette("async").

Stacking order

Decorators stack, and in a %@% b %@% f, a is outermost. The order changes what each one sees. This is the order that works for the common cases, from outside to inside:

validate_args()      reject bad input before doing any work
fallback()           use a default only once everything below has given up
circuit_breaker()    fail fast when the service is clearly down
cache / lru_cache()  skip the work for a repeated call
retry()              try again when a call fails
rate_limit()         throttle every attempt, retries included
timeout()            cap each attempt
log_call()           log the call itself

You will rarely need all of them. Skip the ones you do not need and keep the rest in this order.

n <- 0
fetch := validate_args(url = is.character) %@%
  fallback(value = NA_character_) %@%
  retry(stop = stop_after_attempt(3)) %@%
  function(url) {
    n <<- n + 1
    if (n < 3) stop("not yet")
    paste("response from", url)
  }
fetch("example.com")
## [1] "response from example.com"

The reasons behind the order:

  • validate_args() outermost. A bad argument is the caller’s mistake. Retrying or caching it only repeats the mistake.
  • fallback() outside retry() and circuit_breaker(). The default is used once retries are spent or the circuit is open, not after the first failure.
  • circuit_breaker() outside retry(). An open circuit rejects the call before any retries happen.
  • rate_limit() and timeout() inside retry(). Each attempt is then throttled and capped. Outside it, only whole calls would be, and retries could still exceed the limit or run without one.

Put the caches where you want them to sit. Outside retry(), a successful result is cached once. Because only a returned value is stored, an error is never cached.