KaSourceModificationService¶

interface KaSourceModificationService : KaEngineService

KaSourceModificationService is an engine service which handles cache invalidation after source code changes:

For local changes (in-block modification and whitespace), the service invalidates local caches for, e.g., classes. This level of granularity cannot be reached by any module-level event (see KotlinModificationEvent), because the specific entity to invalidate needs to be discovered via the changed PsiElement.
For non-local changes (out-of-block modification), the service publishes a module out-of-block modification event.

The service performs change locality detection to classify a change to a given PsiElement in terms of KaSourceModificationLocality.

An element may be submitted to consideration before or after the actual modification is performed, but service implementations don't guarantee that the invalidation behavior is the same for before/after instances of the same modification.

While out-of-block modification events can be published to the message bus directly, there is currently no infrastructure for publishing in-block modification. Hence, platforms will need to use KaSourceModificationService for more granular cache invalidation, or as a last resort publish out-of-block modification events for all changes.

Types¶

`Companion`¶

object Companion

Functions¶

ancestorAffectedByInBlockModification¶

abstract fun ancestorAffectedByInBlockModification(element: PsiElement): PsiElement?

Returns the farthest ancestor PsiElement of element which would be affected by an in-block modification to element, or null if it's uncertain.

detectLocality¶

abstract fun detectLocality(element: PsiElement, modificationType: KaElementModificationType): KaSourceModificationLocality

Classifies the modification of element and its modificationType in terms of KaSourceModificationLocality, as described in the KDoc of KaSourceModificationService. The function may be called before and after element's modification.

If KaElementModificationType.Unknown is specified, the service must classify the modification pessimistically, so specifying a narrower modification type is usually beneficial.

Here are some examples for which element to pass:

element should be a KtNamedFunction after dropping the function's body.
element should be a KtBlockExpression after replacing one body expression with another.
element should be a KtBlockExpression after adding a body to a function without a body.
If element is the parent of an already removed element, KaElementModificationType.ElementRemoved should contain the removed element.
If element is the replacement, KaElementModificationType.ElementReplaced should contain the replaced element.

handleElementModification¶

fun KaSourceModificationService.handleElementModification(element: PsiElement, modificationType: KaElementModificationType)

Detects the modification locality of element and handles the corresponding cache invalidation.

This is a convenience function that combines KaSourceModificationService.detectLocality and KaSourceModificationService.handleInvalidation.

The function must be called from a write action.

See also

KaSourceModificationService.detectLocality
KaSourceModificationService.handleInvalidation

handleInvalidation¶

abstract fun handleInvalidation(element: PsiElement, modificationLocality: KaSourceModificationLocality)

Handles the cache invalidation for element's modification based on the detected modificationLocality.