diff options
Diffstat (limited to 'src/main/scala/xyz/driver/core/Refresh.scala')
-rw-r--r-- | src/main/scala/xyz/driver/core/Refresh.scala | 20 |
1 files changed, 16 insertions, 4 deletions
diff --git a/src/main/scala/xyz/driver/core/Refresh.scala b/src/main/scala/xyz/driver/core/Refresh.scala index ca28da7..e66b22f 100644 --- a/src/main/scala/xyz/driver/core/Refresh.scala +++ b/src/main/scala/xyz/driver/core/Refresh.scala @@ -8,8 +8,8 @@ import scala.concurrent.duration.Duration /** A single-value asynchronous cache with TTL. * - * Slightly adapted from Twitter's "util" library - * https://github.com/twitter/util/blob/ae0ab09134414438af9dfaa88a4613cecbff4741/util-cache/src/main/scala/com/twitter/cache/Refresh.scala + * Slightly adapted from + * [[https://github.com/twitter/util/blob/ae0ab09134414438af9dfaa88a4613cecbff4741/util-cache/src/main/scala/com/twitter/cache/Refresh.scala Twitter's "util" library]] * * Released under the Apache License 2.0. */ @@ -17,15 +17,27 @@ object Refresh { /** Creates a function that will provide a cached value for a given time-to-live (TTL). * + * It avoids the "thundering herd" problem if multiple requests arrive + * simultanously and the cached value has expired or is unset. + * + * Usage example: * {{{ * def freshToken(): Future[String] = // expensive network call to get an access token - * val getToken: Future[String] = Refresh.every(1.hour)(freshToken()) + * val getToken: () => Future[String] = Refresh.every(1.hour)(freshToken()) * * getToken() // new token is issued * getToken() // subsequent calls use the cached token * // wait 1 hour * getToken() // new token is issued - * }}} */ + * }}} + * + * @param ttl Time-To-Live duration to cache a computed value. + * @param compute Call-by-name operation that eventually computes a value to + * be cached. Note that if the computation (i.e. the future) fails, the value + * is not cached. + * @param ec The execution context in which valeu computations will be run. + * @return A zero-arg function that returns the cached value. + */ def every[A](ttl: Duration)(compute: => Future[A])(implicit ec: ExecutionContext): () => Future[A] = { val ref = new AtomicReference[(Future[A], Instant)]( (Future.failed(new NoSuchElementException("Cached value was never computed")), Instant.MIN) |