#5612

Committed 11 Jul 2026 03:47PM UTC coverage: 71.292% (-28.7%) from 100.0%

Build # #5612

Build Type

push

github

Committed by

ben-manes

Commit Message

Preserve timestamps on a raced same-instance refresh

The automatic refreshIfNeeded path checked for an equal-value reload
before the ABA/ownership check and returned without preserving the
timestamps, so a reload completing after a concurrent put(k,
sameInstance) did a full update — shifting the entry's expiration
forward by the reload's in-flight duration and stomping the write.
Mirror the explicit-refresh fix: check ownership first. An owned
reload installs the value (refreshing metadata even for a same
instance), while a raced reload preserves the write's timestamps and
only notifies REPLACED when the value differs.

Coverage Stats

2957 of 4134 branches covered (71.53%)

3 of 3 new or added lines in 1 file covered. (100.0%)

2408 existing lines in 53 files now uncovered.

5980 of 8388 relevant lines covered (71.29%)

0.71 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.12

/caffeine/src/main/java/com/github/benmanes/caffeine/cache/References.java

/*
 * Copyright 2015 Ben Manes. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.github.benmanes.caffeine.cache;

import static java.util.Locale.US;
import static java.util.Objects.requireNonNull;

import java.lang.ref.ReferenceQueue;
import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.util.Objects;

import org.jspecify.annotations.Nullable;

/**
 * Static utility methods and classes pertaining to weak and soft references.
 *
 * @author ben.manes@gmail.com (Ben Manes)
 */
@SuppressWarnings({"EqualsWhichDoesntCheckParameterClass",
    "PMD.MissingStaticMethodInNonInstantiatableClass"})
final class References {

  private References() {}

  /** A weak or soft reference that includes the entry's key reference. */
  interface InternalReference<E> {

    /**
     * Returns this reference object's referent. If this reference object has been cleared, either
     * by the program or by the garbage collector, then this method returns {@code null}.
     *
     * @return The object to which this reference refers, or {@code null} if this reference object
     *         has been cleared
     */
    @Nullable E get();

    /**
     * Returns the key that is associated to the cache entry holding this reference. If the cache
     * holds keys strongly, this is that key instance. Otherwise, the cache holds keys weakly and
     * the {@link WeakKeyReference} is returned.
     *
     * @return the key that is associated to the cached entry
     */
    Object getKeyReference();

    /**
     * Returns {@code true} if the arguments is a {@linkplain InternalReference} that holds the
     * same element. A weakly or softly held element is compared using identity equality.
     *
     * @param object the reference object with which to compare
     * @return {@code true} if this object is the same as the argument; {@code false} otherwise
     */
    default boolean referenceEquals(@Nullable Object object) {
      if (object == this) {
        return true;
      } else if (object instanceof InternalReference<?>) {
        var referent = (InternalReference<?>) object;
        return (get() == referent.get());
      }
      return false;
    }

    /**
     * Returns {@code true} if the arguments is a {@linkplain InternalReference} that holds an
     * equivalent element as determined by {@link Object#equals}.
     *
     * @param object the reference object with which to compare
     * @return {@code true} if this object is equivalent by {@link Object#equals} as the argument;
     *         {@code false} otherwise
     */
    default boolean objectEquals(@Nullable Object object) {
      if (object == this) {
        return true;
      } else if (object instanceof InternalReference<?>) {
        var referent = (InternalReference<?>) object;
        return Objects.equals(get(), referent.get());
      }
      return false;
    }
  }

  /**
   * A short-lived adapter used for looking up an entry in the cache where the keys are weakly held.
   * This {@linkplain InternalReference} implementation is not suitable for storing in the cache as
   * the key is strongly held.
   */
  static final class LookupKeyReference<K> implements InternalReference<K> {
    private final int hashCode;
    private final K key;

    public LookupKeyReference(K key) {
      this.hashCode = System.identityHashCode(key);
      this.key = requireNonNull(key);
    }

    @Override
    public K get() {
      return key;
    }

    @Override
    public Object getKeyReference() {
      return this;
    }

    @Override
    public boolean equals(@Nullable Object object) {
      return referenceEquals(object);
    }

    @Override
    public int hashCode() {
      return hashCode;
    }

    @Override
    public String toString() {
      return String.format(US,
          "%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);
    }
  }

  /**
   * A short-lived adapter used for looking up an entry in the cache where the keys are weakly held.
   * This {@linkplain InternalReference} implementation is not suitable for storing in the cache as
   * the key is strongly held.
   */
  static final class LookupKeyEqualsReference<K> implements InternalReference<K> {
    private final int hashCode;
    private final K key;

    public LookupKeyEqualsReference(K key) {
      this.hashCode = key.hashCode();
      this.key = requireNonNull(key);
    }

    @Override
    public K get() {
      return key;
    }

    @Override
    public Object getKeyReference() {
      return this;
    }

    @Override
    public boolean equals(@Nullable Object object) {
      return objectEquals(object);
    }

    @Override
    public int hashCode() {
      return hashCode;
    }

    @Override
    public String toString() {
      return String.format(US,
          "%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);
    }
  }

  /**
   * The key in a cache that holds keys weakly. This class retains the key's identity hash code in
   * the advent that the key is reclaimed so that the entry can be removed from the cache in
   * constant time.
   */
  static class WeakKeyReference<K> extends WeakReference<@Nullable K>
      implements InternalReference<K> {
    private final int hashCode;

    public WeakKeyReference(@Nullable K key, @Nullable ReferenceQueue<K> queue) {
      super(key, queue);
      hashCode = System.identityHashCode(key);
    }

    @Override
    public final Object getKeyReference() {
      return this;
    }

    @Override
    public final boolean equals(@Nullable Object object) {
      return referenceEquals(object);
    }

    @Override
    public final int hashCode() {
      return hashCode;
    }

    @Override
    public final String toString() {
      return String.format(US,
          "%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);
    }
  }

  /**
   * The key in a cache that holds the key weakly and uses equals equivalence. This class retains
   * the key's hash code in the advent that the key is reclaimed so that the entry can be removed
   * from the cache in constant time.
   */
  static final class WeakKeyEqualsReference<K>
      extends WeakReference<K> implements InternalReference<K> {
    private final int hashCode;

    public WeakKeyEqualsReference(K key, @Nullable ReferenceQueue<K> queue) {
      super(key, queue);
      hashCode = key.hashCode();
    }

    @Override
    public Object getKeyReference() {
      return this;
    }

    @Override
    public boolean equals(@Nullable Object object) {
      return objectEquals(object);
    }

    @Override
    public int hashCode() {
      return hashCode;
    }

    @Override
    public String toString() {
      return String.format(US,
          "%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);
    }
  }

  /**
   * The value in a cache that holds values weakly. This class retains a reference to the key in
   * the advent that the value is reclaimed so that the entry can be removed from the cache in
   * constant time.
   */
  static final class WeakValueReference<V> extends WeakReference<@Nullable V>
      implements InternalReference<V> {
    private Object keyReference;

    public WeakValueReference(Object keyReference,
        @Nullable V value, @Nullable ReferenceQueue<V> queue) {
      super(value, queue);
      this.keyReference = keyReference;
    }

    @Override
    public Object getKeyReference() {
      return keyReference;
    }

    public void setKeyReference(Object keyReference) {
      this.keyReference = keyReference;
    }

    @Override
    public boolean equals(@Nullable Object object) {
      return referenceEquals(object);
    }

    @Override
    public int hashCode() {
      V value = get();
      return (value == null) ? 0 : value.hashCode();
    }

    @Override
    public String toString() {
      return String.format(US, "%s{value=%s}", getClass().getSimpleName(), get());
    }
  }

  /**
   * The value in a cache that holds values softly. This class retains a reference to the key in
   * the advent that the value is reclaimed so that the entry can be removed from the cache in
   * constant time.
   */
  static final class SoftValueReference<V> extends SoftReference<@Nullable V>
      implements InternalReference<V> {
    private Object keyReference;

    public SoftValueReference(Object keyReference,
        @Nullable V value, @Nullable ReferenceQueue<V> queue) {
      super(value, queue);
      this.keyReference = keyReference;
    }

    @Override
    public Object getKeyReference() {
      return keyReference;
    }

    public void setKeyReference(Object keyReference) {
      this.keyReference = keyReference;
    }

    @Override
    public boolean equals(@Nullable Object object) {
      return referenceEquals(object);
    }

    @Override
    public int hashCode() {
      V value = get();
      return (value == null) ? 0 : value.hashCode();
    }

    @Override
    public String toString() {
      return String.format(US, "%s{value=%s}", getClass().getSimpleName(), get());
    }
  }
}

1	/*
2	* Copyright 2015 Ben Manes. All Rights Reserved.
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16	package com.github.benmanes.caffeine.cache;
17
18	import static java.util.Locale.US;
19	import static java.util.Objects.requireNonNull;
20
21	import java.lang.ref.ReferenceQueue;
22	import java.lang.ref.SoftReference;
23	import java.lang.ref.WeakReference;
24	import java.util.Objects;
25
26	import org.jspecify.annotations.Nullable;
27
28	/**
29	* Static utility methods and classes pertaining to weak and soft references.
30	*
31	* @author ben.manes@gmail.com (Ben Manes)
32	*/
33	@SuppressWarnings({"EqualsWhichDoesntCheckParameterClass",
34	"PMD.MissingStaticMethodInNonInstantiatableClass"})
35	final class References {
36
37	private References() {}
38
39	/** A weak or soft reference that includes the entry's key reference. */
40	interface InternalReference<E> {
41
42	/**
43	* Returns this reference object's referent. If this reference object has been cleared, either
44	* by the program or by the garbage collector, then this method returns {@code null}.
45	*
46	* @return The object to which this reference refers, or {@code null} if this reference object
47	* has been cleared
48	*/
49	@Nullable E get();
50
51	/**
52	* Returns the key that is associated to the cache entry holding this reference. If the cache
53	* holds keys strongly, this is that key instance. Otherwise, the cache holds keys weakly and
54	* the {@link WeakKeyReference} is returned.
55	*
56	* @return the key that is associated to the cached entry
57	*/
58	Object getKeyReference();
59
60	/**
61	* Returns {@code true} if the arguments is a {@linkplain InternalReference} that holds the
62	* same element. A weakly or softly held element is compared using identity equality.
63	*
64	* @param object the reference object with which to compare
65	* @return {@code true} if this object is the same as the argument; {@code false} otherwise
66	*/
67	default boolean referenceEquals(@Nullable Object object) {
68	if (object == this) {	1✔
69	return true;	1✔
70	} else if (object instanceof InternalReference<?>) {	1✔
71	var referent = (InternalReference<?>) object;	1✔
72	return (get() == referent.get());	1✔
73	}
74	return false;	1✔
75	}
76
77	/**
78	* Returns {@code true} if the arguments is a {@linkplain InternalReference} that holds an
79	* equivalent element as determined by {@link Object#equals}.
80	*
81	* @param object the reference object with which to compare
82	* @return {@code true} if this object is equivalent by {@link Object#equals} as the argument;
83	* {@code false} otherwise
84	*/
85	default boolean objectEquals(@Nullable Object object) {
86	if (object == this) {	1✔
87	return true;	1✔
88	} else if (object instanceof InternalReference<?>) {	1✔
89	var referent = (InternalReference<?>) object;	1✔
90	return Objects.equals(get(), referent.get());	1✔
91	}
92	return false;	1✔
93	}
94	}
95
96	/**
97	* A short-lived adapter used for looking up an entry in the cache where the keys are weakly held.
98	* This {@linkplain InternalReference} implementation is not suitable for storing in the cache as
99	* the key is strongly held.
100	*/
101	static final class LookupKeyReference<K> implements InternalReference<K> {
102	private final int hashCode;
103	private final K key;
104
105	public LookupKeyReference(K key) {	1✔
106	this.hashCode = System.identityHashCode(key);	1✔
107	this.key = requireNonNull(key);	1✔
108	}	1✔
109
110	@Override
111	public K get() {
112	return key;	1✔
113	}
114
115	@Override
116	public Object getKeyReference() {
UNCOV 117	return this;	×
118	}
119
120	@Override
121	public boolean equals(@Nullable Object object) {
122	return referenceEquals(object);	1✔
123	}
124
125	@Override
126	public int hashCode() {
127	return hashCode;	1✔
128	}
129
130	@Override
131	public String toString() {
132	return String.format(US,	1✔
133	"%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);	1✔
134	}
135	}
136
137	/**
138	* A short-lived adapter used for looking up an entry in the cache where the keys are weakly held.
139	* This {@linkplain InternalReference} implementation is not suitable for storing in the cache as
140	* the key is strongly held.
141	*/
142	static final class LookupKeyEqualsReference<K> implements InternalReference<K> {
143	private final int hashCode;
144	private final K key;
145
146	public LookupKeyEqualsReference(K key) {	1✔
147	this.hashCode = key.hashCode();	1✔
148	this.key = requireNonNull(key);	1✔
149	}	1✔
150
151	@Override
152	public K get() {
153	return key;	1✔
154	}
155
156	@Override
157	public Object getKeyReference() {
UNCOV 158	return this;	×
159	}
160
161	@Override
162	public boolean equals(@Nullable Object object) {
163	return objectEquals(object);	1✔
164	}
165
166	@Override
167	public int hashCode() {
168	return hashCode;	1✔
169	}
170
171	@Override
172	public String toString() {
173	return String.format(US,	1✔
174	"%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);	1✔
175	}
176	}
177
178	/**
179	* The key in a cache that holds keys weakly. This class retains the key's identity hash code in
180	* the advent that the key is reclaimed so that the entry can be removed from the cache in
181	* constant time.
182	*/
183	static class WeakKeyReference<K> extends WeakReference<@Nullable K>
184	implements InternalReference<K> {
185	private final int hashCode;
186
187	public WeakKeyReference(@Nullable K key, @Nullable ReferenceQueue<K> queue) {
188	super(key, queue);	1✔
189	hashCode = System.identityHashCode(key);	1✔
190	}	1✔
191
192	@Override
193	public final Object getKeyReference() {
UNCOV 194	return this;	×
195	}
196
197	@Override
198	public final boolean equals(@Nullable Object object) {
199	return referenceEquals(object);	1✔
200	}
201
202	@Override
203	public final int hashCode() {
204	return hashCode;	1✔
205	}
206
207	@Override
208	public final String toString() {
209	return String.format(US,	1✔
210	"%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);	1✔
211	}
212	}
213
214	/**
215	* The key in a cache that holds the key weakly and uses equals equivalence. This class retains
216	* the key's hash code in the advent that the key is reclaimed so that the entry can be removed
217	* from the cache in constant time.
218	*/
219	static final class WeakKeyEqualsReference<K>
220	extends WeakReference<K> implements InternalReference<K> {
221	private final int hashCode;
222
223	public WeakKeyEqualsReference(K key, @Nullable ReferenceQueue<K> queue) {
224	super(key, queue);	1✔
225	hashCode = key.hashCode();	1✔
226	}	1✔
227
228	@Override
229	public Object getKeyReference() {
UNCOV 230	return this;	×
231	}
232
233	@Override
234	public boolean equals(@Nullable Object object) {
235	return objectEquals(object);	1✔
236	}
237
238	@Override
239	public int hashCode() {
240	return hashCode;	1✔
241	}
242
243	@Override
244	public String toString() {
245	return String.format(US,	1✔
246	"%s{key=%s, hashCode=%d}", getClass().getSimpleName(), get(), hashCode);	1✔
247	}
248	}
249
250	/**
251	* The value in a cache that holds values weakly. This class retains a reference to the key in
252	* the advent that the value is reclaimed so that the entry can be removed from the cache in
253	* constant time.
254	*/
255	static final class WeakValueReference<V> extends WeakReference<@Nullable V>
256	implements InternalReference<V> {
257	private Object keyReference;
258
259	public WeakValueReference(Object keyReference,
260	@Nullable V value, @Nullable ReferenceQueue<V> queue) {
261	super(value, queue);	1✔
262	this.keyReference = keyReference;	1✔
263	}	1✔
264
265	@Override
266	public Object getKeyReference() {
267	return keyReference;	1✔
268	}
269
270	public void setKeyReference(Object keyReference) {
271	this.keyReference = keyReference;	1✔
272	}	1✔
273
274	@Override
275	public boolean equals(@Nullable Object object) {
276	return referenceEquals(object);	1✔
277	}
278
279	@Override
280	public int hashCode() {
281	V value = get();	1✔
282	return (value == null) ? 0 : value.hashCode();	1✔
283	}
284
285	@Override
286	public String toString() {
287	return String.format(US, "%s{value=%s}", getClass().getSimpleName(), get());	1✔
288	}
289	}
290
291	/**
292	* The value in a cache that holds values softly. This class retains a reference to the key in
293	* the advent that the value is reclaimed so that the entry can be removed from the cache in
294	* constant time.
295	*/
296	static final class SoftValueReference<V> extends SoftReference<@Nullable V>
297	implements InternalReference<V> {
298	private Object keyReference;
299
300	public SoftValueReference(Object keyReference,
301	@Nullable V value, @Nullable ReferenceQueue<V> queue) {
302	super(value, queue);	1✔
303	this.keyReference = keyReference;	1✔
304	}	1✔
305
306	@Override
307	public Object getKeyReference() {
308	return keyReference;	1✔
309	}
310
311	public void setKeyReference(Object keyReference) {
312	this.keyReference = keyReference;	1✔
313	}	1✔
314
315	@Override
316	public boolean equals(@Nullable Object object) {
317	return referenceEquals(object);	1✔
318	}
319
320	@Override
321	public int hashCode() {
322	V value = get();	1✔
323	return (value == null) ? 0 : value.hashCode();	1✔
324	}
325
326	@Override
327	public String toString() {
328	return String.format(US, "%s{value=%s}", getClass().getSimpleName(), get());	1✔
329	}
330	}
331	}

ben-manes / caffeine / #5612

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous