hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

indexing_and_psi_stubs.md: edits

Browse Source
This commit is contained in:
Yann Cébron 2022-03-08 16:54:17 +01:00
parent 91964d2838
commit 37510618ac
1 changed files with 14 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
topics/basics/indexing_and_psi_stubs.md
View File

@ -9,8 +9,8 @@ Plugin developers can use the existing indexes built by the IDE itself and build
It supports two main types of indexes: It supports two main types of indexes:
* [File-based indexes](file_based_indexes.md) * [](file_based_indexes.md)
* [Stub indexes](stub_indexes.md) * [](stub_indexes.md)
File-based indexes are built directly over the content of files. File-based indexes are built directly over the content of files.
Stub indexes are built over serialized *stub trees*. Stub indexes are built over serialized *stub trees*.
@ -18,16 +18,16 @@ A stub tree for a source file is a subset of its PSI tree, which contains only e
Querying a file-based index gets you the set of files matching a specific condition. Querying a file-based index gets you the set of files matching a specific condition.
Querying a stub index gets you the set of matching PSI elements. Querying a stub index gets you the set of matching PSI elements.
Therefore, custom language plugin developers should typically use stub indexes in their plugin implementations. Therefore, custom language plugin developers typically use stub indexes in their plugin implementations.
> [Index Viewer](https://plugins.jetbrains.com/plugin/13029-index-viewer/) is a plugin that helps to inspect indexes' contents and properties. > [Index Viewer](https://plugins.jetbrains.com/plugin/13029-index-viewer/) plugin can be used to inspect indexes' contents and properties.
> >
{type="tip"} {type="tip"}
## Dumb Mode ## Dumb Mode
Indexing is a potentially lengthy process. Indexing is a potentially lengthy process.
It's performed in the background, and during this time, IDE's features are restricted to the ones that don't require index: basic text editing, version control, etc. It's performed in the background, and during this time, IDE features are restricted to the ones that don't require index: basic text editing, version control, etc.
This restriction is managed by [`DumbService`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbService.java). This restriction is managed by [`DumbService`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbService.java).
Violations are reported via [`IndexNotReadyException`](upsource:///platform/core-api/src/com/intellij/openapi/project/IndexNotReadyException.java), please see its javadoc on how to adapt callers. Violations are reported via [`IndexNotReadyException`](upsource:///platform/core-api/src/com/intellij/openapi/project/IndexNotReadyException.java), please see its javadoc on how to adapt callers.
@ -39,26 +39,29 @@ Please see its JavaDoc for more details.
Sometimes, the following conditions hold: Sometimes, the following conditions hold:
* the aggregation functionality of file-based indexes is not needed. * The aggregation functionality of file-based indexes is not needed.
One just needs to calculate some data based on a particular file's contents and cache it on disk. One just needs to calculate some data based on a particular file's contents and cache it on disk.
* eagerly calculating the data for the entire project during indexing isn't needed (e.g., it slows down the indexing, and/or this data probably will ever be required for a minor subset of all project files). * Eagerly calculating the data for the entire project during indexing isn't needed (e.g., it slows down the indexing, and/or this data probably will ever be required for a minor subset of all project files).
* the data can be recalculated lazily on request without significant performance penalties. * The data can be recalculated lazily on request without significant performance penalties.
A [file-based index](file_based_indexes.md) can be used in such cases, but file gists provide a way to perform data calculation lazily, caching on disk, and a more lightweight API. A [file-based index](file_based_indexes.md) can be used in such cases, but file gists provide a way to perform data calculation lazily, caching on disk, and a more lightweight API.
Please see [`VirtualFileGist`](upsource:///platform/indexing-api/src/com/intellij/util/gist/VirtualFileGist.java) and [`PsiFileGist`](upsource:///platform/indexing-api/src/com/intellij/util/gist/PsiFileGist.java) documentation. Please see [`VirtualFileGist`](upsource:///platform/indexing-api/src/com/intellij/util/gist/VirtualFileGist.java) and [`PsiFileGist`](upsource:///platform/indexing-api/src/com/intellij/util/gist/PsiFileGist.java) documentation.
**Example:** **Example:**
- [`ImageInfoIndex`](upsource:///images/src/org/intellij/images/index/ImageInfoIndex.java) calculating image dimensions/bit depth needed to be displayed in specific parts of UI.
- `VirtualFileGist`: [`ImageInfoIndex`](upsource:///images/src/org/intellij/images/index/ImageInfoIndex.java) calculating image dimensions/bit depth needed to be displayed in specific parts of UI.
- `PsiFileGist`: [`JavaSimplePropertyGist`](upsource:///java/java-indexing-impl/src/com/intellij/psi/impl/JavaSimplePropertyGist.kt) providing simple properties in Java
## Improving Indexing Performance ## Improving Indexing Performance
### Performance Metrics ### Performance Metrics
Indexing performance metrics in JSON format are generated in [logs directory](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs) (see [sandbox directory](ide_development_instance.md#the-development-instance-sandbox-directory) for development instance) in 2020.2 and later. Indexing performance metrics in JSON format are generated in [logs directory](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs) (see [sandbox directory](ide_development_instance.md#the-development-instance-sandbox-directory) for development instance) in 2020.2 and later.
These are additionally available in HTML format starting with 2021.1. These are additionally available in HTML format starting with 2021.1.
### Avoid Using AST ### Avoid Using AST
Use lexer information instead of parsed trees if possible. Use [lexer](implementing_lexer.md) information instead of parsed trees if possible.
If impossible, use light AST which doesn't create memory-hungry AST nodes inside, so traversing it might be faster. If impossible, use light AST which doesn't create memory-hungry AST nodes inside, so traversing it might be faster.
Make sure to traverse only the nodes you need to. Make sure to traverse only the nodes you need to.
@ -73,4 +76,4 @@ If a custom language contains lazy-parseable elements that never or rarely conta
### Consider Prebuilt Stubs ### Consider Prebuilt Stubs
If your language has a massive standard library, which is mostly the same for all users, you can avoid stub-indexing it in each installation by providing prebuilt stubs with your distribution. If your language has a massive standard library, which is mostly the same for all users, you can avoid stub-indexing it in each installation by providing prebuilt stubs with your distribution.
See [`PrebuiltStubsProvider`](upsource:///platform/indexing-impl/src/com/intellij/psi/stubs/PrebuiltStubs.kt) extension. <!-- PrebuildStubsProvider is deprecated; someone with more expertise in this should rewrite this piece. --> See [`PrebuiltStubsProvider`](upsource:///platform/indexing-impl/src/com/intellij/psi/stubs/PrebuiltStubs.kt) extension.