Package com.intellij.util

Class IdempotenceChecker

java.lang.Object

com.intellij.util.IdempotenceChecker

public class IdempotenceChecker
extends java.lang.Object

Constructor Summary

Constructors

Constructor and Description
IdempotenceChecker()

Method Summary

Modifier and Type	Method and Description
static <T> void	applyForRandomCheck(T data, java.lang.Object provider, Computable<? extends T> recomputeValue) Call this when accessing an already cached value, so that once in a while (depending on "platform.random.idempotence.check.rate" registry value) the computation is re-run and checked for consistency with that cached value.
static boolean	areRandomChecksEnabled()
static <T> void	checkEquivalence(T existing, T fresh, java.lang.Class<?> providerClass, Computable<? extends T> recomputeValue) Perform some basic checks whether the two given objects are equivalent and interchangeable, as described in e.g CachedValue contract.
static void	disableRandomChecksUntil(Disposable parentDisposable) Useful when your test checks how many times a specific code was called, and random checks make that test flaky.
static boolean	isCurrentThreadInsideRandomCheck()
static boolean	isLoggingEnabled()
static void	logTrace(java.lang.String message) Log a message to help debug checkEquivalence(T, T, java.lang.Class<?>, com.intellij.openapi.util.Computable<? extends T>) failures.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdempotenceChecker

public IdempotenceChecker()

Method Detail

checkEquivalence

public static <T> void checkEquivalence(T existing,
                                        T fresh,
                                        java.lang.Class<?> providerClass,
                                        Computable<? extends T> recomputeValue)

Perform some basic checks whether the two given objects are equivalent and interchangeable, as described in e.g CachedValue contract. This method should be used in places caching results of various computations, which are expected to be idempotent: they can be performed several times, or on multiple threads, and the results should be interchangeable.

What to do if you get an error from here:

• Start by looking carefully at the computation (which usually can be found by navigating the stack trace) and find out why it could be non-idempotent. See common culprits below.
• Add logging inside the computation by using logTrace(java.lang.String).
• If the computation is complex and depends on other caches, you could try to perform IdempotenceChecker.checkEquivalence() for their results as well, localizing the error.
• If it's a test, you could try reproducing and debugging it. To increase the probability of failure, you can temporarily add Registry.get("platform.random.idempotence.check.rate").setValue(1, getTestRootDisposable()) to perform the idempotence check on every cache access. Note that this can make your test much slower.

Common culprits:

• Caching and returning a mutable object (e.g. array or List), which clients then mutate from different threads; to fix, either clone the return value or use unmodifiable wrappers
• Depending on a ThreadLocal or method parameters with different values.
• For failures from applyForRandomCheck(T, java.lang.Object, com.intellij.openapi.util.Computable<? extends T>): outdated cached value (not all dependencies are specified, or their modification counters aren't properly incremented)

Parameters:

existing - the value computed on the first invocation

fresh - the value computed a bit later, expected to be equivalent

providerClass - a class of the function performing the computation, used to prevent reporting the same error multiple times

recomputeValue - optionally, a way to recalculate the value one more time with isLoggingEnabled() true, and include the log collected via logTrace(java.lang.String) into exception report.

areRandomChecksEnabled

public static boolean areRandomChecksEnabled()

Returns:

whether random checks are enabled and it makes sense to call a potentially expensive applyForRandomCheck(T, java.lang.Object, com.intellij.openapi.util.Computable<? extends T>) at all.

disableRandomChecksUntil

public static void disableRandomChecksUntil(Disposable parentDisposable)

Useful when your test checks how many times a specific code was called, and random checks make that test flaky.

applyForRandomCheck

public static <T> void applyForRandomCheck(T data,
                                           java.lang.Object provider,
                                           Computable<? extends T> recomputeValue)

Call this when accessing an already cached value, so that once in a while (depending on "platform.random.idempotence.check.rate" registry value) the computation is re-run and checked for consistency with that cached value.

isCurrentThreadInsideRandomCheck

public static boolean isCurrentThreadInsideRandomCheck()

isLoggingEnabled

public static boolean isLoggingEnabled()

Returns:

whether logTrace(java.lang.String) will actually log anything

logTrace

public static void logTrace(java.lang.String message)

Log a message to help debug checkEquivalence(T, T, java.lang.Class<?>, com.intellij.openapi.util.Computable<? extends T>) failures. When such a failure occurs, the computation can be re-run again with this logging enabled, and the collected log will be included into exception message.