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