MDS/openide
1
0
Fork 0
mirror of https://gitflic.ru/project/openide/openide.git synced 2026-09-27 10:03:11 +07:00
Code Issues Packages Projects Releases Wiki Activity

[core-api] CachedValueProvider: update Javadoc to mention Document as a valid dependency

Browse Source 
GitOrigin-RevId: d7cd9b7aad8ae95b7608b430907284217c0bfe48
This commit is contained in:
Bartek Pacia
2025-09-30 00:42:51 +00:00
committed by intellij-monorepo-bot
parent 9033ee5567
commit 7d7c958cde
1 changed files with 27 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
platform/core-api/src/com/intellij/psi/util/CachedValueProvider.java
+27 -14
View File
@@ -1,7 +1,9 @@
// Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
package com.intellij.psi.util;
import com.intellij.lang.Language;
import com.intellij.openapi.diagnostic.Logger;
import com.intellij.psi.PsiElement;
import com.intellij.util.ArrayUtil;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
@@ -10,8 +12,9 @@ import java.util.Collection;
/**
* A computation (typically a lambda) used by {@link CachedValue} to calculate a result and cache it.
* The provider should not have side effects and shouldn't depend on variables that change during the CachedValue lifetime. See
* {@link CachedValue} documentation for examples.<p></p>
* The provider should not have side effects and shouldn't depend on variables that change during the CachedValue lifetime.
* See {@link CachedValue} documentation for examples.
*
* @param <T> the type of the cached value
*/
@FunctionalInterface
@@ -24,7 +27,8 @@ public interface CachedValueProvider<T> {
Result<T> compute();
/**
* The object holding the value to cache and the dependencies indicating when that value will be outdated
* The object holding the value to cache and the dependencies indicating when that value will be outdated.
*
* @param <T> the type of the cached value
*/
final class Result<T> {
@@ -54,22 +58,29 @@ public interface CachedValueProvider<T> {
}
/**
* Dependency items are used in cached values to remember the state of the environment as it was when the value was computed
* and to compare that to the state of the world when querying {@link CachedValue#getValue()}. The state is remembered as
* a collection of {@code long} values representing some time stamps. When changes occur, these stamps are incremented.<p/>
*
* Dependencies can be following:
* Dependency items are used in a {@link CachedValue cached value} to remember the state of the world as it was when the value was computed
* and to compare that to the state of the world when querying {@link CachedValue#getValue()}.
* <p>
* The state is remembered as a collection of {@code long} values representing some time stamps.
* Whenever changes occur, these stamps are incremented.
* <p>
* Dependencies can be the following:
* <ul>
* <li/>Instances of {@link com.intellij.openapi.util.ModificationTracker} returning stamps explicitly
* <li/>Instances of {@link com.intellij.openapi.util.ModificationTracker ModificationTracker} returning stamps explicitly
* <li/>Constant fields of {@link PsiModificationTracker} class, e.g. {@link PsiModificationTracker#MODIFICATION_COUNT}
* <li/>{@link com.intellij.psi.PsiElement} or {@link com.intellij.openapi.vfs.VirtualFile} objects. Such cache would be dropped
* on any change in the corresponding file
* <li/>Instances of {@link com.intellij.openapi.editor.Document Document} or {@link com.intellij.openapi.vfs.VirtualFile VirtualFile}.
* Invalidated on any change in the corresponding file.
* <li/>Instances of {@link PsiElement}. Invalidated on any change in the {@link PsiElement#getContainingFile() element's containing file}.
* </ul>
* <p>
* If your cached value uses a document instance as an input, you should use that document as a dependency.
* If it uses a PSI as an input, it should use that PSI as a dependency.
*
* @return the dependency items
* @see com.intellij.openapi.util.ModificationTracker
* @see com.intellij.openapi.util.ModificationTracker ModificationTracker
* @see PsiModificationTracker
* @see com.intellij.openapi.roots.ProjectRootModificationTracker
* @see com.intellij.openapi.roots.ProjectRootModificationTracker ProjectRootModificationTracker
* @see PsiModificationTracker#forLanguage(Language)
*/
public Object @NotNull [] getDependencyItems() {
return myDependencyItems;
@@ -77,6 +88,7 @@ public interface CachedValueProvider<T> {
/**
* Creates a result
*
* @see #getDependencyItems()
*/
public static @NotNull <T> Result<T> createSingleDependency(@Nullable T value, @NotNull Object dependency) {
@@ -85,6 +97,7 @@ public interface CachedValueProvider<T> {
/**
* Creates a result
*
* @see #getDependencyItems()
*/
public static @NotNull <T> Result<T> create(@Nullable T value, Object @NotNull ... dependencies) {
@@ -93,11 +106,11 @@ public interface CachedValueProvider<T> {
/**
* Creates a result
*
* @see #getDependencyItems()
*/
public static @NotNull <T> Result<T> create(@Nullable T value, @NotNull Collection<?> dependencies) {
return new Result<>(value, ArrayUtil.toObjectArray(dependencies));
}
}
}