From eeb5b42eee40ef2f795190cc25d816ee17befc70 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Mon, 17 Feb 2025 12:17:04 +0100 Subject: [PATCH] coroutine_execution_contexts.md: Revert the original order until clarified --- .../coroutine_execution_contexts.md | 75 ++++++++++--------- 1 file changed, 39 insertions(+), 36 deletions(-) diff --git a/topics/basics/architectural_overview/coroutines/coroutine_execution_contexts.md b/topics/basics/architectural_overview/coroutines/coroutine_execution_contexts.md index 8264261b8..28f595b25 100644 --- a/topics/basics/architectural_overview/coroutines/coroutine_execution_contexts.md +++ b/topics/basics/architectural_overview/coroutines/coroutine_execution_contexts.md @@ -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 Plugin DevKit | Code | Calling method should be annotated with @RequiresBlockingContext 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*
+ + *_[`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 + 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 Plugin DevKit | Code | Calling method should be annotated with @RequiresBlockingContext 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) - -