mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-27 16:57:49 +08:00
coroutine_execution_contexts.md: Revert the original order until clarified
This commit is contained in:
Karol Lewandowski
parent
39fb9bed74
commit
eeb5b42eee
@ -9,10 +9,10 @@
|
||||
|
||||
The IntelliJ Platform provides APIs that allow tracking the progress of background processes and canceling their execution when they are canceled by a user, or they become obsolete due to some changes in the data model.
|
||||
|
||||
Background processes can be executed in three contexts (from the most to the least preferred):
|
||||
Background processes can be executed in three contexts:
|
||||
- [](#suspending-context)
|
||||
- [](#blocking-context)
|
||||
- [](#progress-indicator) (obsolete since 2024.1)
|
||||
- [](#blocking-context) (should be avoided)
|
||||
|
||||
Currently, the Progress Indicator context is the most widely used approach in the IntelliJ Platform.
|
||||
As the platform's execution model moves towards coroutines, this approach can be considered obsolete.
|
||||
@ -69,10 +69,46 @@ withBackgroundProgress(...) { // or withModalProgress/runWithModalProgressBlocki
|
||||
### Switching to Other Contexts
|
||||
{#suspending-context-switching-to-other-contexts}
|
||||
|
||||
- to [progress indicator](#progress-indicator): unavailable ([`coroutineToIndicator()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt) is an internal API and exists only to aid platform migration)
|
||||
- to [blocking context](#blocking-context): [`blockingContext()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt) - enables `ProgressManager.checkCanceled()`, forwards modality state, etc. This function has an opposite behavior to [`runBlockingCancellable()`](#blocking-context-switching-to-other-contexts).
|
||||
- to [progress indicator](#progress-indicator): unavailable*
|
||||
|
||||
*_[`coroutineToIndicator()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt) is an internal API and exists only to aid platform migration_
|
||||
|
||||
## Blocking Context
|
||||
|
||||
Executing tasks in a blocking context means executing them on a thread without access to the [coroutine context](#suspending-context) (basically, in non-suspending functions) and not under [a progress indicator](#progress-indicator).
|
||||
Such tasks can't be canceled by using coroutines' or progress indicator's cancellation capabilities, which may block threads and consume resources even if the task is no longer relevant.
|
||||
|
||||
Usually, plugins should not execute new code in the blocking context.
|
||||
Always prefer executing tasks in the [suspending context](#suspending-context) or under the [progress indicator](#progress-indicator) if a plugin cannot use Kotlin.
|
||||
|
||||
> Functions which schedule execution via [`Application.executeOnPooledThread()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/Application.java)
|
||||
> and similar methods, and which rely on [`ProgressManager.checkCanceled()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java)
|
||||
> should be annotated with [`@RequiresBlockingContext`](%gh-ic%/platform/core-api/src/com/intellij/util/concurrency/annotations/RequiresBlockingContext.kt)
|
||||
> to inform clients about the required switch to a blocking context.
|
||||
>
|
||||
> Inspection <control>Plugin DevKit | Code | Calling method should be annotated with @RequiresBlockingContext</control> reports missing annotations.
|
||||
|
||||
### Cancellation Check
|
||||
{#blocking-context-cancellation-check}
|
||||
|
||||
- [`ProgressManager.checkCanceled()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java)
|
||||
|
||||
### Progress Reporting
|
||||
{#blocking-context-progress-reporting}
|
||||
|
||||
- unavailable
|
||||
|
||||
### Switching to Other Contexts
|
||||
{#blocking-context-switching-to-other-contexts}
|
||||
|
||||
- to [suspending context](#suspending-context): [`runBlockingCancellable()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt). This function has an opposite behavior to [`blockingContext()`](#suspending-context-switching-to-other-contexts).
|
||||
- to [progress indicator](#progress-indicator): unavailable*<br/>
|
||||
|
||||
*_[`blockingContextToIndicator()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt) is an internal API used only to aid platform migration_
|
||||
|
||||
## Progress Indicator
|
||||
<primary-label ref="obsolete-2024.1"/>
|
||||
|
||||
Code executed via the Progress API
|
||||
([`ProgressManager`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java),
|
||||
@ -103,36 +139,3 @@ See the [](background_processes.md#progress-api) section for details.
|
||||
|
||||
- to [suspending context](#suspending-context): [`runBlockingCancellable`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt)
|
||||
- to [blocking context](#blocking-context): unavailable
|
||||
|
||||
## Blocking Context
|
||||
|
||||
Executing tasks in a blocking context means executing them on a thread without access to the [coroutine context](#suspending-context) (basically, in non-suspending functions) and not under [a progress indicator](#progress-indicator).
|
||||
Such tasks can't be canceled by using coroutines' or progress indicator's cancellation capabilities, which may block threads and consume resources even if the task is no longer relevant.
|
||||
|
||||
Usually, plugins should not execute new code in the blocking context.
|
||||
Always prefer executing tasks in the [suspending context](#suspending-context) or under the [progress indicator](#progress-indicator) if a plugin cannot use Kotlin.
|
||||
|
||||
> Functions which schedule execution via [`Application.executeOnPooledThread()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/Application.java)
|
||||
> and similar methods, and which rely on [`ProgressManager.checkCanceled()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java)
|
||||
> should be annotated with [`@RequiresBlockingContext`](%gh-ic%/platform/core-api/src/com/intellij/util/concurrency/annotations/RequiresBlockingContext.kt)
|
||||
> to inform clients about the required switch to a blocking context.
|
||||
>
|
||||
> Inspection <control>Plugin DevKit | Code | Calling method should be annotated with @RequiresBlockingContext</control> reports missing annotations.
|
||||
|
||||
### Cancellation Check
|
||||
{#blocking-context-cancellation-check}
|
||||
|
||||
- [`ProgressManager.checkCanceled()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java)
|
||||
|
||||
### Progress Reporting
|
||||
{#blocking-context-progress-reporting}
|
||||
|
||||
Progress reporting is not available in the blocking context.
|
||||
|
||||
### Switching to Other Contexts
|
||||
{#blocking-context-switching-to-other-contexts}
|
||||
|
||||
- to [suspending context](#suspending-context): [`runBlockingCancellable()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt). This function has an opposite behavior to [`blockingContext()`](#suspending-context-switching-to-other-contexts).
|
||||
- to [progress indicator](#progress-indicator): unavailable ([`blockingContextToIndicator()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/progress/coroutines.kt) is an internal API and exists only to aid platform migration)
|
||||
|
||||
<include from="snippets.md" element-id="missingContent"/>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user