These advantages can take
        [many forms](https://github.com/google/guava/wiki/PhilosophyExplained#utility), but taking
        the time to discuss them in detail will make it much clearer why this feature should be
        added to Guava.


        Please fill out the following fields to give us a better understanding of your proposed
        feature and its potential value for other Guava users.

    // different value
    assertFalse(segment.replace(key, hash, oldValue, newValue));
    assertEquals(1, segment.count);
    assertSame(newValue, segment.get(key, hash));

    // cleared
    segment.setWeakValueReferenceForTesting(entry, oldValueRef);
    oldValueRef.clear();
    assertFalse(segment.replace(key, hash, oldValue, newValue));
    assertEquals(0, segment.count);

    // different value
    assertFalse(segment.replace(key, hash, oldValue, newValue));
    assertEquals(1, segment.count);
    assertSame(newValue, segment.get(key, hash));

    // cleared
    segment.setWeakValueReferenceForTesting(entry, oldValueRef);
    oldValueRef.clear();
    assertFalse(segment.replace(key, hash, oldValue, newValue));
    assertEquals(0, segment.count);

 * after the garbage collector reclaims the referent. This is a simpler alternative to using a
 * {@link ReferenceQueue}.
 *
 * <p>Unlike a normal phantom reference, this reference will be cleared automatically.
 *
 * @author Bob Lee
 * @since 2.0
 */
@J2ktIncompatible
@GwtIncompatible
public abstract class FinalizablePhantomReference<T> extends PhantomReference<T>
    implements FinalizableReference {

    /**
     * Injects the proxy information into the specified repositories. For each repository that is matched by a proxy,
     * its proxy data will be set accordingly. Repositories without a matching proxy will have their proxy cleared.
     * Note: This method must be called after {@link #injectMirror(List, List)} or the repositories will end up
     * with the wrong proxies.
     *

     *   <li>If this field's value == null because it originally belonged to another thread and that
     *       thread cleared it, we still know that it's not associated with our thread
     *   <li>If this field's value == null because it was associated with our thread and was
     *       cleared, we know that we're not executing inline any more
     * </ul>
     *

{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}

It will be clearly marked as deprecated in the interactive docs:

<img src="/img/tutorial/path-operation-configuration/image04.png">

Check how deprecated and non-deprecated *path operations* look like:

 * </ul>
 *
 * <p>Because of this situation, any public method accepting an iterable should invoke the {@code
 * iterator} method only once, and should be tested using this class. Exceptions to this rule should
 * be clearly documented.
 *
 * <p>Note that although your APIs should be liberal in what they accept, your methods which
 * <i>return</i> iterables should make every attempt to return ones of the robust variety.
 *

        new TearDown() {

          @Override
          public void tearDown() throws Exception {
            synchronized (result.lock) {
              assertEquals(
                  "The test should have cleared the stack (say, by virtue of running runTearDown)",
                  0,
                  result.stack.size());
            }
          }
        });
    return result;
  }

* **Reduced review friction**: Less time spent on spelling corrections during PR reviews
* **Professional appearance**: Consistent APIs and documentation appear more polished
* **Clearer contribution guidelines**: [CONTRIBUTING.md](../../CONTRIBUTING.md) now includes this requirement

### Negative Consequences