001/* 002 * Copyright (C) 2009 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.cache; 016 017import static com.google.common.base.Preconditions.checkArgument; 018import static com.google.common.base.Preconditions.checkNotNull; 019import static com.google.common.base.Preconditions.checkState; 020 021import com.google.common.annotations.GwtCompatible; 022import com.google.common.annotations.GwtIncompatible; 023import com.google.common.base.Ascii; 024import com.google.common.base.Equivalence; 025import com.google.common.base.MoreObjects; 026import com.google.common.base.Supplier; 027import com.google.common.base.Suppliers; 028import com.google.common.base.Ticker; 029import com.google.common.cache.AbstractCache.SimpleStatsCounter; 030import com.google.common.cache.AbstractCache.StatsCounter; 031import com.google.common.cache.LocalCache.Strength; 032import com.google.errorprone.annotations.CanIgnoreReturnValue; 033import java.lang.ref.SoftReference; 034import java.lang.ref.WeakReference; 035import java.util.ConcurrentModificationException; 036import java.util.IdentityHashMap; 037import java.util.Map; 038import java.util.concurrent.TimeUnit; 039import java.util.logging.Level; 040import java.util.logging.Logger; 041import javax.annotation.CheckForNull; 042 043/** 044 * A builder of {@link LoadingCache} and {@link Cache} instances. 045 * 046 * <h2>Prefer <a href="https://github.com/ben-manes/caffeine/wiki">Caffeine</a> over Guava's caching 047 * API</h2> 048 * 049 * <p>The successor to Guava's caching API is <a 050 * href="https://github.com/ben-manes/caffeine/wiki">Caffeine</a>. Its API is designed to make it a 051 * nearly drop-in replacement -- though it requires Java 8 APIs, is not available for Android or 052 * GWT/j2cl, and may have <a href="https://github.com/ben-manes/caffeine/wiki/Guava">different 053 * (usually better) behavior</a> when multiple threads attempt concurrent mutations. Its equivalent 054 * to {@code CacheBuilder} is its <a 055 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/Caffeine.html">{@code 056 * Caffeine}</a> class. Caffeine offers better performance, more features (including asynchronous 057 * loading), and fewer <a 058 * href="https://github.com/google/guava/issues?q=is%3Aopen+is%3Aissue+label%3Apackage%3Dcache+label%3Atype%3Ddefect">bugs</a>. 059 * 060 * <p>Caffeine defines its own interfaces (<a 061 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/Cache.html">{@code 062 * Cache}</a>, <a 063 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/LoadingCache.html">{@code 064 * LoadingCache}</a>, <a 065 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/CacheLoader.html">{@code 066 * CacheLoader}</a>, etc.), so you can use Caffeine without needing to use any Guava types. 067 * Caffeine's types are better than Guava's, especially for <a 068 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/AsyncLoadingCache.html">their 069 * deep support for asynchronous operations</a>. But if you want to migrate to Caffeine with minimal 070 * code changes, you can use <a 071 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/guava/latest/com.github.benmanes.caffeine.guava/com/github/benmanes/caffeine/guava/CaffeinatedGuava.html">its 072 * {@code CaffeinatedGuava} adapter class</a>, which lets you build a Guava {@code Cache} or a Guava 073 * {@code LoadingCache} backed by a Guava {@code CacheLoader}. 074 * 075 * <p>Caffeine's API for asynchronous operations uses {@code CompletableFuture}: <a 076 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/AsyncLoadingCache.html#get(K)">{@code 077 * AsyncLoadingCache.get}</a> returns a {@code CompletableFuture}, and implementations of <a 078 * href="https://www.javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/latest/com.github.benmanes.caffeine/com/github/benmanes/caffeine/cache/AsyncCacheLoader.html#asyncLoad(K,java.util.concurrent.Executor)">{@code 079 * AsyncCacheLoader.asyncLoad}</a> must return a {@code CompletableFuture}. Users of Guava's {@link 080 * com.google.common.util.concurrent.ListenableFuture} can adapt between the two {@code Future} 081 * types by using <a href="https://github.com/lukas-krecan/future-converter#java8-guava">{@code 082 * net.javacrumbs.futureconverter.java8guava.FutureConverter}</a>. 083 * 084 * <h2>More on {@code CacheBuilder}</h2> 085 * 086 * {@code CacheBuilder} builds caches with any combination of the following features: 087 * 088 * <ul> 089 * <li>automatic loading of entries into the cache 090 * <li>least-recently-used eviction when a maximum size is exceeded (note that the cache is 091 * divided into segments, each of which does LRU internally) 092 * <li>time-based expiration of entries, measured since last access or last write 093 * <li>keys automatically wrapped in {@code WeakReference} 094 * <li>values automatically wrapped in {@code WeakReference} or {@code SoftReference} 095 * <li>notification of evicted (or otherwise removed) entries 096 * <li>accumulation of cache access statistics 097 * </ul> 098 * 099 * <p>These features are all optional; caches can be created using all or none of them. By default, 100 * cache instances created by {@code CacheBuilder} will not perform any type of eviction. 101 * 102 * <p>Usage example: 103 * 104 * <pre>{@code 105 * LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder() 106 * .maximumSize(10000) 107 * .expireAfterWrite(10, TimeUnit.MINUTES) 108 * .removalListener(MY_LISTENER) 109 * .build( 110 * new CacheLoader<Key, Graph>() { 111 * public Graph load(Key key) throws AnyException { 112 * return createExpensiveGraph(key); 113 * } 114 * }); 115 * }</pre> 116 * 117 * <p>Or equivalently, 118 * 119 * <pre>{@code 120 * // In real life this would come from a command-line flag or config file 121 * String spec = "maximumSize=10000,expireAfterWrite=10m"; 122 * 123 * LoadingCache<Key, Graph> graphs = CacheBuilder.from(spec) 124 * .removalListener(MY_LISTENER) 125 * .build( 126 * new CacheLoader<Key, Graph>() { 127 * public Graph load(Key key) throws AnyException { 128 * return createExpensiveGraph(key); 129 * } 130 * }); 131 * }</pre> 132 * 133 * <p>The returned cache implements all optional operations of the {@link LoadingCache} and {@link 134 * Cache} interfaces. The {@code asMap} view (and its collection views) have <i>weakly consistent 135 * iterators</i>. This means that they are safe for concurrent use, but if other threads modify the 136 * cache after the iterator is created, it is undefined which of these changes, if any, are 137 * reflected in that iterator. These iterators never throw {@link ConcurrentModificationException}. 138 * 139 * <p><b>Note:</b> by default, the returned cache uses equality comparisons (the {@link 140 * Object#equals equals} method) to determine equality for keys or values. However, if {@link 141 * #weakKeys} was specified, the cache uses identity ({@code ==}) comparisons instead for keys. 142 * Likewise, if {@link #weakValues} or {@link #softValues} was specified, the cache uses identity 143 * comparisons for values. 144 * 145 * <p>Entries are automatically evicted from the cache when any of {@link #maximumSize(long) 146 * maximumSize}, {@link #maximumWeight(long) maximumWeight}, {@link #expireAfterWrite 147 * expireAfterWrite}, {@link #expireAfterAccess expireAfterAccess}, {@link #weakKeys weakKeys}, 148 * {@link #weakValues weakValues}, or {@link #softValues softValues} are requested. 149 * 150 * <p>If {@link #maximumSize(long) maximumSize} or {@link #maximumWeight(long) maximumWeight} is 151 * requested entries may be evicted on each cache modification. 152 * 153 * <p>If {@link #expireAfterWrite expireAfterWrite} or {@link #expireAfterAccess expireAfterAccess} 154 * is requested entries may be evicted on each cache modification, on occasional cache accesses, or 155 * on calls to {@link Cache#cleanUp}. Expired entries may be counted by {@link Cache#size}, but will 156 * never be visible to read or write operations. 157 * 158 * <p>If {@link #weakKeys weakKeys}, {@link #weakValues weakValues}, or {@link #softValues 159 * softValues} are requested, it is possible for a key or value present in the cache to be reclaimed 160 * by the garbage collector. Entries with reclaimed keys or values may be removed from the cache on 161 * each cache modification, on occasional cache accesses, or on calls to {@link Cache#cleanUp}; such 162 * entries may be counted in {@link Cache#size}, but will never be visible to read or write 163 * operations. 164 * 165 * <p>Certain cache configurations will result in the accrual of periodic maintenance tasks which 166 * will be performed during write operations, or during occasional read operations in the absence of 167 * writes. The {@link Cache#cleanUp} method of the returned cache will also perform maintenance, but 168 * calling it should not be necessary with a high throughput cache. Only caches built with {@link 169 * #removalListener removalListener}, {@link #expireAfterWrite expireAfterWrite}, {@link 170 * #expireAfterAccess expireAfterAccess}, {@link #weakKeys weakKeys}, {@link #weakValues 171 * weakValues}, or {@link #softValues softValues} perform periodic maintenance. 172 * 173 * <p>The caches produced by {@code CacheBuilder} are serializable, and the deserialized caches 174 * retain all the configuration properties of the original cache. Note that the serialized form does 175 * <i>not</i> include cache contents, but only configuration. 176 * 177 * <p>See the Guava User Guide article on <a 178 * href="https://github.com/google/guava/wiki/CachesExplained">caching</a> for a higher-level 179 * explanation. 180 * 181 * @param <K> the most general key type this builder will be able to create caches for. This is 182 * normally {@code Object} unless it is constrained by using a method like {@code 183 * #removalListener}. Cache keys may not be null. 184 * @param <V> the most general value type this builder will be able to create caches for. This is 185 * normally {@code Object} unless it is constrained by using a method like {@code 186 * #removalListener}. Cache values may not be null. 187 * @author Charles Fry 188 * @author Kevin Bourrillion 189 * @since 10.0 190 */ 191@GwtCompatible(emulated = true) 192@ElementTypesAreNonnullByDefault 193public final class CacheBuilder<K, V> { 194 private static final int DEFAULT_INITIAL_CAPACITY = 16; 195 private static final int DEFAULT_CONCURRENCY_LEVEL = 4; 196 197 @SuppressWarnings("GoodTime") // should be a java.time.Duration 198 private static final int DEFAULT_EXPIRATION_NANOS = 0; 199 200 @SuppressWarnings("GoodTime") // should be a java.time.Duration 201 private static final int DEFAULT_REFRESH_NANOS = 0; 202 203 static final Supplier<? extends StatsCounter> NULL_STATS_COUNTER = 204 Suppliers.ofInstance( 205 new StatsCounter() { 206 @Override 207 public void recordHits(int count) {} 208 209 @Override 210 public void recordMisses(int count) {} 211 212 @SuppressWarnings("GoodTime") // b/122668874 213 @Override 214 public void recordLoadSuccess(long loadTime) {} 215 216 @SuppressWarnings("GoodTime") // b/122668874 217 @Override 218 public void recordLoadException(long loadTime) {} 219 220 @Override 221 public void recordEviction() {} 222 223 @Override 224 public CacheStats snapshot() { 225 return EMPTY_STATS; 226 } 227 }); 228 static final CacheStats EMPTY_STATS = new CacheStats(0, 0, 0, 0, 0, 0); 229 230 /* 231 * We avoid using a method reference or lambda here for now: 232 * 233 * - method reference: Inside Google, CacheBuilder is used from the implementation of a custom 234 * ClassLoader that is sometimes used as a system classloader. That's a problem because 235 * method-reference linking tries to look up the system classloader, and it fails because there 236 * isn't one yet. 237 * 238 * - lambda: Outside Google, we got a report of a similar problem in 239 * https://github.com/google/guava/issues/6565 240 */ 241 @SuppressWarnings("AnonymousToLambda") 242 static final Supplier<StatsCounter> CACHE_STATS_COUNTER = 243 new Supplier<StatsCounter>() { 244 @Override 245 public StatsCounter get() { 246 return new SimpleStatsCounter(); 247 } 248 }; 249 250 enum NullListener implements RemovalListener<Object, Object> { 251 INSTANCE; 252 253 @Override 254 public void onRemoval(RemovalNotification<Object, Object> notification) {} 255 } 256 257 enum OneWeigher implements Weigher<Object, Object> { 258 INSTANCE; 259 260 @Override 261 public int weigh(Object key, Object value) { 262 return 1; 263 } 264 } 265 266 static final Ticker NULL_TICKER = 267 new Ticker() { 268 @Override 269 public long read() { 270 return 0; 271 } 272 }; 273 274 // We use a holder class to delay initialization: https://github.com/google/guava/issues/6566 275 private static final class LoggerHolder { 276 static final Logger logger = Logger.getLogger(CacheBuilder.class.getName()); 277 } 278 279 static final int UNSET_INT = -1; 280 281 boolean strictParsing = true; 282 283 int initialCapacity = UNSET_INT; 284 int concurrencyLevel = UNSET_INT; 285 long maximumSize = UNSET_INT; 286 long maximumWeight = UNSET_INT; 287 @CheckForNull Weigher<? super K, ? super V> weigher; 288 289 @CheckForNull Strength keyStrength; 290 @CheckForNull Strength valueStrength; 291 292 @SuppressWarnings("GoodTime") // should be a java.time.Duration 293 long expireAfterWriteNanos = UNSET_INT; 294 295 @SuppressWarnings("GoodTime") // should be a java.time.Duration 296 long expireAfterAccessNanos = UNSET_INT; 297 298 @SuppressWarnings("GoodTime") // should be a java.time.Duration 299 long refreshNanos = UNSET_INT; 300 301 @CheckForNull Equivalence<Object> keyEquivalence; 302 @CheckForNull Equivalence<Object> valueEquivalence; 303 304 @CheckForNull RemovalListener<? super K, ? super V> removalListener; 305 @CheckForNull Ticker ticker; 306 307 Supplier<? extends StatsCounter> statsCounterSupplier = NULL_STATS_COUNTER; 308 309 private CacheBuilder() {} 310 311 /** 312 * Constructs a new {@code CacheBuilder} instance with default settings, including strong keys, 313 * strong values, and no automatic eviction of any kind. 314 * 315 * <p>Note that while this return type is {@code CacheBuilder<Object, Object>}, type parameters on 316 * the {@link #build} methods allow you to create a cache of any key and value type desired. 317 */ 318 public static CacheBuilder<Object, Object> newBuilder() { 319 return new CacheBuilder<>(); 320 } 321 322 /** 323 * Constructs a new {@code CacheBuilder} instance with the settings specified in {@code spec}. 324 * 325 * @since 12.0 326 */ 327 @GwtIncompatible // To be supported 328 public static CacheBuilder<Object, Object> from(CacheBuilderSpec spec) { 329 return spec.toCacheBuilder().lenientParsing(); 330 } 331 332 /** 333 * Constructs a new {@code CacheBuilder} instance with the settings specified in {@code spec}. 334 * This is especially useful for command-line configuration of a {@code CacheBuilder}. 335 * 336 * @param spec a String in the format specified by {@link CacheBuilderSpec} 337 * @since 12.0 338 */ 339 @GwtIncompatible // To be supported 340 public static CacheBuilder<Object, Object> from(String spec) { 341 return from(CacheBuilderSpec.parse(spec)); 342 } 343 344 /** 345 * Enables lenient parsing. Useful for tests and spec parsing. 346 * 347 * @return this {@code CacheBuilder} instance (for chaining) 348 */ 349 @GwtIncompatible // To be supported 350 @CanIgnoreReturnValue 351 CacheBuilder<K, V> lenientParsing() { 352 strictParsing = false; 353 return this; 354 } 355 356 /** 357 * Sets a custom {@code Equivalence} strategy for comparing keys. 358 * 359 * <p>By default, the cache uses {@link Equivalence#identity} to determine key equality when 360 * {@link #weakKeys} is specified, and {@link Equivalence#equals()} otherwise. 361 * 362 * @return this {@code CacheBuilder} instance (for chaining) 363 */ 364 @GwtIncompatible // To be supported 365 @CanIgnoreReturnValue 366 CacheBuilder<K, V> keyEquivalence(Equivalence<Object> equivalence) { 367 checkState(keyEquivalence == null, "key equivalence was already set to %s", keyEquivalence); 368 keyEquivalence = checkNotNull(equivalence); 369 return this; 370 } 371 372 Equivalence<Object> getKeyEquivalence() { 373 return MoreObjects.firstNonNull(keyEquivalence, getKeyStrength().defaultEquivalence()); 374 } 375 376 /** 377 * Sets a custom {@code Equivalence} strategy for comparing values. 378 * 379 * <p>By default, the cache uses {@link Equivalence#identity} to determine value equality when 380 * {@link #weakValues} or {@link #softValues} is specified, and {@link Equivalence#equals()} 381 * otherwise. 382 * 383 * @return this {@code CacheBuilder} instance (for chaining) 384 */ 385 @GwtIncompatible // To be supported 386 @CanIgnoreReturnValue 387 CacheBuilder<K, V> valueEquivalence(Equivalence<Object> equivalence) { 388 checkState( 389 valueEquivalence == null, "value equivalence was already set to %s", valueEquivalence); 390 this.valueEquivalence = checkNotNull(equivalence); 391 return this; 392 } 393 394 Equivalence<Object> getValueEquivalence() { 395 return MoreObjects.firstNonNull(valueEquivalence, getValueStrength().defaultEquivalence()); 396 } 397 398 /** 399 * Sets the minimum total size for the internal hash tables. For example, if the initial capacity 400 * is {@code 60}, and the concurrency level is {@code 8}, then eight segments are created, each 401 * having a hash table of size eight. Providing a large enough estimate at construction time 402 * avoids the need for expensive resizing operations later, but setting this value unnecessarily 403 * high wastes memory. 404 * 405 * @return this {@code CacheBuilder} instance (for chaining) 406 * @throws IllegalArgumentException if {@code initialCapacity} is negative 407 * @throws IllegalStateException if an initial capacity was already set 408 */ 409 @CanIgnoreReturnValue 410 public CacheBuilder<K, V> initialCapacity(int initialCapacity) { 411 checkState( 412 this.initialCapacity == UNSET_INT, 413 "initial capacity was already set to %s", 414 this.initialCapacity); 415 checkArgument(initialCapacity >= 0); 416 this.initialCapacity = initialCapacity; 417 return this; 418 } 419 420 int getInitialCapacity() { 421 return (initialCapacity == UNSET_INT) ? DEFAULT_INITIAL_CAPACITY : initialCapacity; 422 } 423 424 /** 425 * Guides the allowed concurrency among update operations. Used as a hint for internal sizing. The 426 * table is internally partitioned to try to permit the indicated number of concurrent updates 427 * without contention. Because assignment of entries to these partitions is not necessarily 428 * uniform, the actual concurrency observed may vary. Ideally, you should choose a value to 429 * accommodate as many threads as will ever concurrently modify the table. Using a significantly 430 * higher value than you need can waste space and time, and a significantly lower value can lead 431 * to thread contention. But overestimates and underestimates within an order of magnitude do not 432 * usually have much noticeable impact. A value of one permits only one thread to modify the cache 433 * at a time, but since read operations and cache loading computations can proceed concurrently, 434 * this still yields higher concurrency than full synchronization. 435 * 436 * <p>Defaults to 4. <b>Note:</b>The default may change in the future. If you care about this 437 * value, you should always choose it explicitly. 438 * 439 * <p>The current implementation uses the concurrency level to create a fixed number of hashtable 440 * segments, each governed by its own write lock. The segment lock is taken once for each explicit 441 * write, and twice for each cache loading computation (once prior to loading the new value, and 442 * once after loading completes). Much internal cache management is performed at the segment 443 * granularity. For example, access queues and write queues are kept per segment when they are 444 * required by the selected eviction algorithm. As such, when writing unit tests it is not 445 * uncommon to specify {@code concurrencyLevel(1)} in order to achieve more deterministic eviction 446 * behavior. 447 * 448 * <p>Note that future implementations may abandon segment locking in favor of more advanced 449 * concurrency controls. 450 * 451 * @return this {@code CacheBuilder} instance (for chaining) 452 * @throws IllegalArgumentException if {@code concurrencyLevel} is nonpositive 453 * @throws IllegalStateException if a concurrency level was already set 454 */ 455 @CanIgnoreReturnValue 456 public CacheBuilder<K, V> concurrencyLevel(int concurrencyLevel) { 457 checkState( 458 this.concurrencyLevel == UNSET_INT, 459 "concurrency level was already set to %s", 460 this.concurrencyLevel); 461 checkArgument(concurrencyLevel > 0); 462 this.concurrencyLevel = concurrencyLevel; 463 return this; 464 } 465 466 int getConcurrencyLevel() { 467 return (concurrencyLevel == UNSET_INT) ? DEFAULT_CONCURRENCY_LEVEL : concurrencyLevel; 468 } 469 470 /** 471 * Specifies the maximum number of entries the cache may contain. 472 * 473 * <p>Note that the cache <b>may evict an entry before this limit is exceeded</b>. For example, in 474 * the current implementation, when {@code concurrencyLevel} is greater than {@code 1}, each 475 * resulting segment inside the cache <i>independently</i> limits its own size to approximately 476 * {@code maximumSize / concurrencyLevel}. 477 * 478 * <p>When eviction is necessary, the cache evicts entries that are less likely to be used again. 479 * For example, the cache may evict an entry because it hasn't been used recently or very often. 480 * 481 * <p>If {@code maximumSize} is zero, elements will be evicted immediately after being loaded into 482 * cache. This can be useful in testing, or to disable caching temporarily. 483 * 484 * <p>This feature cannot be used in conjunction with {@link #maximumWeight}. 485 * 486 * @param maximumSize the maximum size of the cache 487 * @return this {@code CacheBuilder} instance (for chaining) 488 * @throws IllegalArgumentException if {@code maximumSize} is negative 489 * @throws IllegalStateException if a maximum size or weight was already set 490 */ 491 @CanIgnoreReturnValue 492 public CacheBuilder<K, V> maximumSize(long maximumSize) { 493 checkState( 494 this.maximumSize == UNSET_INT, "maximum size was already set to %s", this.maximumSize); 495 checkState( 496 this.maximumWeight == UNSET_INT, 497 "maximum weight was already set to %s", 498 this.maximumWeight); 499 checkState(this.weigher == null, "maximum size can not be combined with weigher"); 500 checkArgument(maximumSize >= 0, "maximum size must not be negative"); 501 this.maximumSize = maximumSize; 502 return this; 503 } 504 505 /** 506 * Specifies the maximum weight of entries the cache may contain. Weight is determined using the 507 * {@link Weigher} specified with {@link #weigher}, and use of this method requires a 508 * corresponding call to {@link #weigher} prior to calling {@link #build}. 509 * 510 * <p>Note that the cache <b>may evict an entry before this limit is exceeded</b>. For example, in 511 * the current implementation, when {@code concurrencyLevel} is greater than {@code 1}, each 512 * resulting segment inside the cache <i>independently</i> limits its own weight to approximately 513 * {@code maximumWeight / concurrencyLevel}. 514 * 515 * <p>When eviction is necessary, the cache evicts entries that are less likely to be used again. 516 * For example, the cache may evict an entry because it hasn't been used recently or very often. 517 * 518 * <p>If {@code maximumWeight} is zero, elements will be evicted immediately after being loaded 519 * into cache. This can be useful in testing, or to disable caching temporarily. 520 * 521 * <p>Note that weight is only used to determine whether the cache is over capacity; it has no 522 * effect on selecting which entry should be evicted next. 523 * 524 * <p>This feature cannot be used in conjunction with {@link #maximumSize}. 525 * 526 * @param maximumWeight the maximum total weight of entries the cache may contain 527 * @return this {@code CacheBuilder} instance (for chaining) 528 * @throws IllegalArgumentException if {@code maximumWeight} is negative 529 * @throws IllegalStateException if a maximum weight or size was already set 530 * @since 11.0 531 */ 532 @GwtIncompatible // To be supported 533 @CanIgnoreReturnValue 534 public CacheBuilder<K, V> maximumWeight(long maximumWeight) { 535 checkState( 536 this.maximumWeight == UNSET_INT, 537 "maximum weight was already set to %s", 538 this.maximumWeight); 539 checkState( 540 this.maximumSize == UNSET_INT, "maximum size was already set to %s", this.maximumSize); 541 checkArgument(maximumWeight >= 0, "maximum weight must not be negative"); 542 this.maximumWeight = maximumWeight; 543 return this; 544 } 545 546 /** 547 * Specifies the weigher to use in determining the weight of entries. Entry weight is taken into 548 * consideration by {@link #maximumWeight(long)} when determining which entries to evict, and use 549 * of this method requires a corresponding call to {@link #maximumWeight(long)} prior to calling 550 * {@link #build}. Weights are measured and recorded when entries are inserted into the cache, and 551 * are thus effectively static during the lifetime of a cache entry. 552 * 553 * <p>When the weight of an entry is zero it will not be considered for size-based eviction 554 * (though it still may be evicted by other means). 555 * 556 * <p><b>Important note:</b> Instead of returning <em>this</em> as a {@code CacheBuilder} 557 * instance, this method returns {@code CacheBuilder<K1, V1>}. From this point on, either the 558 * original reference or the returned reference may be used to complete configuration and build 559 * the cache, but only the "generic" one is type-safe. That is, it will properly prevent you from 560 * building caches whose key or value types are incompatible with the types accepted by the 561 * weigher already provided; the {@code CacheBuilder} type cannot do this. For best results, 562 * simply use the standard method-chaining idiom, as illustrated in the documentation at top, 563 * configuring a {@code CacheBuilder} and building your {@link Cache} all in a single statement. 564 * 565 * <p><b>Warning:</b> if you ignore the above advice, and use this {@code CacheBuilder} to build a 566 * cache whose key or value type is incompatible with the weigher, you will likely experience a 567 * {@link ClassCastException} at some <i>undefined</i> point in the future. 568 * 569 * @param weigher the weigher to use in calculating the weight of cache entries 570 * @return this {@code CacheBuilder} instance (for chaining) 571 * @throws IllegalArgumentException if {@code size} is negative 572 * @throws IllegalStateException if a maximum size was already set 573 * @since 11.0 574 */ 575 @GwtIncompatible // To be supported 576 @CanIgnoreReturnValue // TODO(b/27479612): consider removing this 577 public <K1 extends K, V1 extends V> CacheBuilder<K1, V1> weigher( 578 Weigher<? super K1, ? super V1> weigher) { 579 checkState(this.weigher == null); 580 if (strictParsing) { 581 checkState( 582 this.maximumSize == UNSET_INT, 583 "weigher can not be combined with maximum size (%s provided)", 584 this.maximumSize); 585 } 586 587 // safely limiting the kinds of caches this can produce 588 @SuppressWarnings("unchecked") 589 CacheBuilder<K1, V1> me = (CacheBuilder<K1, V1>) this; 590 me.weigher = checkNotNull(weigher); 591 return me; 592 } 593 594 long getMaximumWeight() { 595 if (expireAfterWriteNanos == 0 || expireAfterAccessNanos == 0) { 596 return 0; 597 } 598 return (weigher == null) ? maximumSize : maximumWeight; 599 } 600 601 // Make a safe contravariant cast now so we don't have to do it over and over. 602 @SuppressWarnings("unchecked") 603 <K1 extends K, V1 extends V> Weigher<K1, V1> getWeigher() { 604 return (Weigher<K1, V1>) MoreObjects.firstNonNull(weigher, OneWeigher.INSTANCE); 605 } 606 607 /** 608 * Specifies that each key (not value) stored in the cache should be wrapped in a {@link 609 * WeakReference} (by default, strong references are used). 610 * 611 * <p><b>Warning:</b> when this method is used, the resulting cache will use identity ({@code ==}) 612 * comparison to determine equality of keys. Its {@link Cache#asMap} view will therefore 613 * technically violate the {@link Map} specification (in the same way that {@link IdentityHashMap} 614 * does). 615 * 616 * <p>Entries with keys that have been garbage collected may be counted in {@link Cache#size}, but 617 * will never be visible to read or write operations; such entries are cleaned up as part of the 618 * routine maintenance described in the class javadoc. 619 * 620 * @return this {@code CacheBuilder} instance (for chaining) 621 * @throws IllegalStateException if the key strength was already set 622 */ 623 @GwtIncompatible // java.lang.ref.WeakReference 624 @CanIgnoreReturnValue 625 public CacheBuilder<K, V> weakKeys() { 626 return setKeyStrength(Strength.WEAK); 627 } 628 629 @CanIgnoreReturnValue 630 CacheBuilder<K, V> setKeyStrength(Strength strength) { 631 checkState(keyStrength == null, "Key strength was already set to %s", keyStrength); 632 keyStrength = checkNotNull(strength); 633 return this; 634 } 635 636 Strength getKeyStrength() { 637 return MoreObjects.firstNonNull(keyStrength, Strength.STRONG); 638 } 639 640 /** 641 * Specifies that each value (not key) stored in the cache should be wrapped in a {@link 642 * WeakReference} (by default, strong references are used). 643 * 644 * <p>Weak values will be garbage collected once they are weakly reachable. This makes them a poor 645 * candidate for caching; consider {@link #softValues} instead. 646 * 647 * <p><b>Note:</b> when this method is used, the resulting cache will use identity ({@code ==}) 648 * comparison to determine equality of values. 649 * 650 * <p>Entries with values that have been garbage collected may be counted in {@link Cache#size}, 651 * but will never be visible to read or write operations; such entries are cleaned up as part of 652 * the routine maintenance described in the class javadoc. 653 * 654 * @return this {@code CacheBuilder} instance (for chaining) 655 * @throws IllegalStateException if the value strength was already set 656 */ 657 @GwtIncompatible // java.lang.ref.WeakReference 658 @CanIgnoreReturnValue 659 public CacheBuilder<K, V> weakValues() { 660 return setValueStrength(Strength.WEAK); 661 } 662 663 /** 664 * Specifies that each value (not key) stored in the cache should be wrapped in a {@link 665 * SoftReference} (by default, strong references are used). Softly-referenced objects will be 666 * garbage-collected in a <i>globally</i> least-recently-used manner, in response to memory 667 * demand. 668 * 669 * <p><b>Warning:</b> in most circumstances it is better to set a per-cache {@linkplain 670 * #maximumSize(long) maximum size} instead of using soft references. You should only use this 671 * method if you are well familiar with the practical consequences of soft references. 672 * 673 * <p><b>Note:</b> when this method is used, the resulting cache will use identity ({@code ==}) 674 * comparison to determine equality of values. 675 * 676 * <p>Entries with values that have been garbage collected may be counted in {@link Cache#size}, 677 * but will never be visible to read or write operations; such entries are cleaned up as part of 678 * the routine maintenance described in the class javadoc. 679 * 680 * @return this {@code CacheBuilder} instance (for chaining) 681 * @throws IllegalStateException if the value strength was already set 682 */ 683 @GwtIncompatible // java.lang.ref.SoftReference 684 @CanIgnoreReturnValue 685 public CacheBuilder<K, V> softValues() { 686 return setValueStrength(Strength.SOFT); 687 } 688 689 @CanIgnoreReturnValue 690 CacheBuilder<K, V> setValueStrength(Strength strength) { 691 checkState(valueStrength == null, "Value strength was already set to %s", valueStrength); 692 valueStrength = checkNotNull(strength); 693 return this; 694 } 695 696 Strength getValueStrength() { 697 return MoreObjects.firstNonNull(valueStrength, Strength.STRONG); 698 } 699 700 /** 701 * Specifies that each entry should be automatically removed from the cache once a fixed duration 702 * has elapsed after the entry's creation, or the most recent replacement of its value. 703 * 704 * <p>When {@code duration} is zero, this method hands off to {@link #maximumSize(long) 705 * maximumSize}{@code (0)}, ignoring any otherwise-specified maximum size or weight. This can be 706 * useful in testing, or to disable caching temporarily without a code change. 707 * 708 * <p>Expired entries may be counted in {@link Cache#size}, but will never be visible to read or 709 * write operations. Expired entries are cleaned up as part of the routine maintenance described 710 * in the class javadoc. 711 * 712 * @param duration the length of time after an entry is created that it should be automatically 713 * removed 714 * @param unit the unit that {@code duration} is expressed in 715 * @return this {@code CacheBuilder} instance (for chaining) 716 * @throws IllegalArgumentException if {@code duration} is negative 717 * @throws IllegalStateException if {@link #expireAfterWrite} was already set 718 */ 719 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 720 @CanIgnoreReturnValue 721 public CacheBuilder<K, V> expireAfterWrite(long duration, TimeUnit unit) { 722 checkState( 723 expireAfterWriteNanos == UNSET_INT, 724 "expireAfterWrite was already set to %s ns", 725 expireAfterWriteNanos); 726 checkArgument(duration >= 0, "duration cannot be negative: %s %s", duration, unit); 727 this.expireAfterWriteNanos = unit.toNanos(duration); 728 return this; 729 } 730 731 @SuppressWarnings("GoodTime") // nanos internally, should be Duration 732 long getExpireAfterWriteNanos() { 733 return (expireAfterWriteNanos == UNSET_INT) ? DEFAULT_EXPIRATION_NANOS : expireAfterWriteNanos; 734 } 735 736 /** 737 * Specifies that each entry should be automatically removed from the cache once a fixed duration 738 * has elapsed after the entry's creation, the most recent replacement of its value, or its last 739 * access. Access time is reset by all cache read and write operations (including {@code 740 * Cache.asMap().get(Object)} and {@code Cache.asMap().put(K, V)}), but not by {@code 741 * containsKey(Object)}, nor by operations on the collection-views of {@link Cache#asMap}. So, for 742 * example, iterating through {@code Cache.asMap().entrySet()} does not reset access time for the 743 * entries you retrieve. 744 * 745 * <p>When {@code duration} is zero, this method hands off to {@link #maximumSize(long) 746 * maximumSize}{@code (0)}, ignoring any otherwise-specified maximum size or weight. This can be 747 * useful in testing, or to disable caching temporarily without a code change. 748 * 749 * <p>Expired entries may be counted in {@link Cache#size}, but will never be visible to read or 750 * write operations. Expired entries are cleaned up as part of the routine maintenance described 751 * in the class javadoc. 752 * 753 * @param duration the length of time after an entry is last accessed that it should be 754 * automatically removed 755 * @param unit the unit that {@code duration} is expressed in 756 * @return this {@code CacheBuilder} instance (for chaining) 757 * @throws IllegalArgumentException if {@code duration} is negative 758 * @throws IllegalStateException if {@link #expireAfterAccess} was already set 759 */ 760 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 761 @CanIgnoreReturnValue 762 public CacheBuilder<K, V> expireAfterAccess(long duration, TimeUnit unit) { 763 checkState( 764 expireAfterAccessNanos == UNSET_INT, 765 "expireAfterAccess was already set to %s ns", 766 expireAfterAccessNanos); 767 checkArgument(duration >= 0, "duration cannot be negative: %s %s", duration, unit); 768 this.expireAfterAccessNanos = unit.toNanos(duration); 769 return this; 770 } 771 772 @SuppressWarnings("GoodTime") // nanos internally, should be Duration 773 long getExpireAfterAccessNanos() { 774 return (expireAfterAccessNanos == UNSET_INT) 775 ? DEFAULT_EXPIRATION_NANOS 776 : expireAfterAccessNanos; 777 } 778 779 /** 780 * Specifies that active entries are eligible for automatic refresh once a fixed duration has 781 * elapsed after the entry's creation, or the most recent replacement of its value. The semantics 782 * of refreshes are specified in {@link LoadingCache#refresh}, and are performed by calling {@link 783 * CacheLoader#reload}. 784 * 785 * <p>As the default implementation of {@link CacheLoader#reload} is synchronous, it is 786 * recommended that users of this method override {@link CacheLoader#reload} with an asynchronous 787 * implementation; otherwise refreshes will be performed during unrelated cache read and write 788 * operations. 789 * 790 * <p>Currently automatic refreshes are performed when the first stale request for an entry 791 * occurs. The request triggering refresh will make a synchronous call to {@link 792 * CacheLoader#reload} 793 * and immediately return the new value if the returned future is complete, and the old value 794 * otherwise. 795 * 796 * <p><b>Note:</b> <i>all exceptions thrown during refresh will be logged and then swallowed</i>. 797 * 798 * @param duration the length of time after an entry is created that it should be considered 799 * stale, and thus eligible for refresh 800 * @param unit the unit that {@code duration} is expressed in 801 * @return this {@code CacheBuilder} instance (for chaining) 802 * @throws IllegalArgumentException if {@code duration} is negative 803 * @throws IllegalStateException if {@link #refreshAfterWrite} was already set 804 * @since 11.0 805 */ 806 @GwtIncompatible // To be supported (synchronously). 807 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 808 @CanIgnoreReturnValue 809 public CacheBuilder<K, V> refreshAfterWrite(long duration, TimeUnit unit) { 810 checkNotNull(unit); 811 checkState(refreshNanos == UNSET_INT, "refresh was already set to %s ns", refreshNanos); 812 checkArgument(duration > 0, "duration must be positive: %s %s", duration, unit); 813 this.refreshNanos = unit.toNanos(duration); 814 return this; 815 } 816 817 @SuppressWarnings("GoodTime") // nanos internally, should be Duration 818 long getRefreshNanos() { 819 return (refreshNanos == UNSET_INT) ? DEFAULT_REFRESH_NANOS : refreshNanos; 820 } 821 822 /** 823 * Specifies a nanosecond-precision time source for this cache. By default, {@link 824 * System#nanoTime} is used. 825 * 826 * <p>The primary intent of this method is to facilitate testing of caches with a fake or mock 827 * time source. 828 * 829 * @return this {@code CacheBuilder} instance (for chaining) 830 * @throws IllegalStateException if a ticker was already set 831 */ 832 @CanIgnoreReturnValue 833 public CacheBuilder<K, V> ticker(Ticker ticker) { 834 checkState(this.ticker == null); 835 this.ticker = checkNotNull(ticker); 836 return this; 837 } 838 839 Ticker getTicker(boolean recordsTime) { 840 if (ticker != null) { 841 return ticker; 842 } 843 return recordsTime ? Ticker.systemTicker() : NULL_TICKER; 844 } 845 846 /** 847 * Specifies a listener instance that caches should notify each time an entry is removed for any 848 * {@linkplain RemovalCause reason}. Each cache created by this builder will invoke this listener 849 * as part of the routine maintenance described in the class documentation above. 850 * 851 * <p><b>Warning:</b> after invoking this method, do not continue to use <i>this</i> cache builder 852 * reference; instead use the reference this method <i>returns</i>. At runtime, these point to the 853 * same instance, but only the returned reference has the correct generic type information to 854 * ensure type safety. For best results, use the standard method-chaining idiom illustrated in the 855 * class documentation above, configuring a builder and building your cache in a single statement. 856 * Failure to heed this advice can result in a {@link ClassCastException} being thrown by a cache 857 * operation at some <i>undefined</i> point in the future. 858 * 859 * <p><b>Warning:</b> any exception thrown by {@code listener} will <i>not</i> be propagated to 860 * the {@code Cache} user, only logged via a {@link Logger}. 861 * 862 * @return the cache builder reference that should be used instead of {@code this} for any 863 * remaining configuration and cache building 864 * @return this {@code CacheBuilder} instance (for chaining) 865 * @throws IllegalStateException if a removal listener was already set 866 */ 867 public <K1 extends K, V1 extends V> CacheBuilder<K1, V1> removalListener( 868 RemovalListener<? super K1, ? super V1> listener) { 869 checkState(this.removalListener == null); 870 871 // safely limiting the kinds of caches this can produce 872 @SuppressWarnings("unchecked") 873 CacheBuilder<K1, V1> me = (CacheBuilder<K1, V1>) this; 874 me.removalListener = checkNotNull(listener); 875 return me; 876 } 877 878 // Make a safe contravariant cast now so we don't have to do it over and over. 879 @SuppressWarnings("unchecked") 880 <K1 extends K, V1 extends V> RemovalListener<K1, V1> getRemovalListener() { 881 return (RemovalListener<K1, V1>) 882 MoreObjects.firstNonNull(removalListener, NullListener.INSTANCE); 883 } 884 885 /** 886 * Enable the accumulation of {@link CacheStats} during the operation of the cache. Without this 887 * {@link Cache#stats} will return zero for all statistics. Note that recording stats requires 888 * bookkeeping to be performed with each operation, and thus imposes a performance penalty on 889 * cache operation. 890 * 891 * @return this {@code CacheBuilder} instance (for chaining) 892 * @since 12.0 (previously, stats collection was automatic) 893 */ 894 @CanIgnoreReturnValue 895 public CacheBuilder<K, V> recordStats() { 896 statsCounterSupplier = CACHE_STATS_COUNTER; 897 return this; 898 } 899 900 boolean isRecordingStats() { 901 return statsCounterSupplier == CACHE_STATS_COUNTER; 902 } 903 904 Supplier<? extends StatsCounter> getStatsCounterSupplier() { 905 return statsCounterSupplier; 906 } 907 908 /** 909 * Builds a cache, which either returns an already-loaded value for a given key or atomically 910 * computes or retrieves it using the supplied {@code CacheLoader}. If another thread is currently 911 * loading the value for this key, simply waits for that thread to finish and returns its loaded 912 * value. Note that multiple threads can concurrently load values for distinct keys. 913 * 914 * <p>This method does not alter the state of this {@code CacheBuilder} instance, so it can be 915 * invoked again to create multiple independent caches. 916 * 917 * @param loader the cache loader used to obtain new values 918 * @return a cache having the requested features 919 */ 920 public <K1 extends K, V1 extends V> LoadingCache<K1, V1> build( 921 CacheLoader<? super K1, V1> loader) { 922 checkWeightWithWeigher(); 923 return new LocalCache.LocalLoadingCache<>(this, loader); 924 } 925 926 /** 927 * Builds a cache which does not automatically load values when keys are requested. 928 * 929 * <p>Consider {@link #build(CacheLoader)} instead, if it is feasible to implement a {@code 930 * CacheLoader}. 931 * 932 * <p>This method does not alter the state of this {@code CacheBuilder} instance, so it can be 933 * invoked again to create multiple independent caches. 934 * 935 * @return a cache having the requested features 936 * @since 11.0 937 */ 938 public <K1 extends K, V1 extends V> Cache<K1, V1> build() { 939 checkWeightWithWeigher(); 940 checkNonLoadingCache(); 941 return new LocalCache.LocalManualCache<>(this); 942 } 943 944 private void checkNonLoadingCache() { 945 checkState(refreshNanos == UNSET_INT, "refreshAfterWrite requires a LoadingCache"); 946 } 947 948 private void checkWeightWithWeigher() { 949 if (weigher == null) { 950 checkState(maximumWeight == UNSET_INT, "maximumWeight requires weigher"); 951 } else { 952 if (strictParsing) { 953 checkState(maximumWeight != UNSET_INT, "weigher requires maximumWeight"); 954 } else { 955 if (maximumWeight == UNSET_INT) { 956 LoggerHolder.logger.log( 957 Level.WARNING, "ignoring weigher specified without maximumWeight"); 958 } 959 } 960 } 961 } 962 963 /** 964 * Returns a string representation for this CacheBuilder instance. The exact form of the returned 965 * string is not specified. 966 */ 967 @Override 968 public String toString() { 969 MoreObjects.ToStringHelper s = MoreObjects.toStringHelper(this); 970 if (initialCapacity != UNSET_INT) { 971 s.add("initialCapacity", initialCapacity); 972 } 973 if (concurrencyLevel != UNSET_INT) { 974 s.add("concurrencyLevel", concurrencyLevel); 975 } 976 if (maximumSize != UNSET_INT) { 977 s.add("maximumSize", maximumSize); 978 } 979 if (maximumWeight != UNSET_INT) { 980 s.add("maximumWeight", maximumWeight); 981 } 982 if (expireAfterWriteNanos != UNSET_INT) { 983 s.add("expireAfterWrite", expireAfterWriteNanos + "ns"); 984 } 985 if (expireAfterAccessNanos != UNSET_INT) { 986 s.add("expireAfterAccess", expireAfterAccessNanos + "ns"); 987 } 988 if (keyStrength != null) { 989 s.add("keyStrength", Ascii.toLowerCase(keyStrength.toString())); 990 } 991 if (valueStrength != null) { 992 s.add("valueStrength", Ascii.toLowerCase(valueStrength.toString())); 993 } 994 if (keyEquivalence != null) { 995 s.addValue("keyEquivalence"); 996 } 997 if (valueEquivalence != null) { 998 s.addValue("valueEquivalence"); 999 } 1000 if (removalListener != null) { 1001 s.addValue("removalListener"); 1002 } 1003 return s.toString(); 1004 } 1005}