From 981a8ff91125b6e06b346e24158cde9aa779ba1c Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Thu, 20 Feb 2025 12:00:15 +0100 Subject: [PATCH] execution_contexts.topic: Rename Job Context to Coroutine Execution Context --- .../threading/execution_contexts.topic | 108 ++++++++---------- 1 file changed, 50 insertions(+), 58 deletions(-) diff --git a/topics/basics/architectural_overview/threading/execution_contexts.topic b/topics/basics/architectural_overview/threading/execution_contexts.topic index bc911ce22..ab481c8ca 100644 --- a/topics/basics/architectural_overview/threading/execution_contexts.topic +++ b/topics/basics/architectural_overview/threading/execution_contexts.topic @@ -12,7 +12,7 @@ execution when they are canceled by a user, or they become obsolete due to some changes in the data model.

- +

Available execution contexts differ depending on the IntelliJ Platform version. For the details, select the required tab below.

@@ -21,7 +21,7 @@

Background processes can be executed in two contexts:

-
  • — available since 2024.2
    • +
  • — available since 2024.2
  • — obsolete since 2024.1
    •  @@ -29,44 +29,36 @@ As the platform's execution model moves towards coroutines, this approach can be considered obsolete.

    -

    Starting with 2024.2, it is recommended to execute new code in the - Job context.

    +

    Starting with 2024.2, it is recommended to execute new code in the .

    The following sections explain the contexts and provide information about process cancellation, progress tracking, and switching between contexts.

    - - + - Suspending and Blocking contexts available in 2024.1 have been unified into the Job context. + Suspending and Blocking contexts available in 2024.1 have been unified into the Coroutine Execution Context. See the     Reconsider blockingContext issue for more details. -

    Code executed in Kotlin coroutines is executed in the Job context. +

    Code executed in Kotlin coroutines is executed in the Coroutine Execution Context. Since 2024.2, coroutines are recommended for executing background tasks to maximize CPU utilization. Note that executing code in coroutines is possible only with Kotlin.

    - While code executed in the Job context should use suspending functions, + While code executed in the Coroutine Execution Context should use suspending functions, sometimes it is required to call non-suspending/blocking APIs that use methods such as ProgressManager.checkCanceled() or ModalityState.defaultModalityState(). - Since 2024.2, these methods work as expected without the need to switch to the blocking context. + Since 2024.2, these methods work as expected without the need to switch to the Blocking Context.

    - The "Job" word in the name refers to the - - Job class, which is used for task cancellation in suspending and non-suspending - functions. - -

    Inspection Plugin DevKit | Code | Forbidden in suspend context method usage - reports calling blocking code from suspending context. + reports calling blocking code from Suspending Context. While this is not an error, it is recommended to use suspending counterparts if they exist.

    @@ -85,7 +77,7 @@

    Starting with 2024.1, it is recommended to execute new code in the - suspending context.

    + Suspending Context.

    @@ -93,43 +85,43 @@ -

    Code executed in Kotlin coroutines is executed in a suspending context. +

    Code executed in Kotlin coroutines is executed in the Suspending Context. Since 2024.1, this context is recommended for executing background tasks to maximize CPU utilization. Note that executing code in coroutines is possible only with Kotlin.

    -

    In a suspending context, methods such as ProgressManager.checkCanceled() or ModalityState.defaultModalityState() +

    In the Suspending Context, methods such as ProgressManager.checkCanceled() or ModalityState.defaultModalityState() won't have any effect. Therefore, if their behavior is required, switch to a blocking context.

    Inspection Plugin DevKit | Code | Forbidden in suspend context method usage - reports calling blocking code from suspending context. + reports calling blocking code from the Suspending Context.

    -

    Executing tasks in a blocking context means executing them on a thread without access to the Executing tasks in the Blocking Context means executing them on a thread without access to the coroutine context (basically, in non-suspending functions) - and not under a progress indicator. + and not under the Progress Indicator. Such tasks can still be canceled, but they can't report progress.

    -

    Plugins should not execute new code in the blocking context. - Always prefer executing tasks in the suspending context or - under the progress indicator if a plugin cannot use Kotlin.

    +

    Plugins should not execute new code in the Blocking Context. + Always prefer executing tasks in the Suspending Context or + under the Progress Indicator if a plugin cannot use Kotlin.

    - -

    Functions which schedule execution via Application.executeOnPooledThread() - and similar methods, and which rely on ProgressManager.checkCanceled() - should be annotated with @RequiresBlockingContext - to inform clients about the required switch to a blocking context.

    +

    Functions which schedule execution via + + Application.executeOnPooledThread() + and similar methods, and which rely on + + ProgressManager.checkCanceled() should be annotated with + + @RequiresBlockingContext to inform clients about the required switch to + the Blocking Context.

    Inspection Plugin DevKit | Code | Calling method should be annotated with @RequiresBlockingContext - - reports missing annotations. + reports missing annotations.

    @@ -143,10 +135,10 @@ (ProgressManager, ProgressIndicator, etc.) - is executed in a progress indicator context. + is executed in the Progress Indicator execution context. See the section for details.

    -

    Executing code under the progress indicator is obsolete since 2024.1. +

    Executing code under the Progress Indicator is obsolete since 2024.1. It is advised to use Kotlin coroutines in new code.

    Please note that obsolete status does not mean deprecation. Executing code using the Progress API is still allowed, but coroutines are recommended as a more @@ -167,7 +159,7 @@ - +
    Job ContextCoroutine Execution Context
  • @@ -193,7 +185,7 @@ - +
    Suspending ContextSuspending Context
  • ensureActive() @@ -203,7 +195,7 @@ Note that ProgressManager.checkCanceled() - does not work in the suspending context. + does not work in the Suspending Context. To enable it, switch to blockingContext(), if it is not possible to change the code. @@ -234,8 +226,8 @@ - - +
    Job Context + Coroutine Execution Context
  • ProgressStep - a step-based progress reporting (see its KDoc for details) @@ -283,8 +275,8 @@ - - + + @@ -310,12 +302,12 @@
    Suspending ContextSuspending Context
    - - + + - + @@ -332,7 +324,7 @@ coroutineToIndicator() is an experimental API, which was originally internal and created to aid platform migration. - It is not recommended to switch from the Job context to the progress indicator. + It is not recommended to switch from the Coroutine Execution Context to the Progress Indicator. Use it only if there is no other option. @@ -341,7 +333,7 @@
    - To Job ContextTo Progress Indicator + To Coroutine Execution ContextTo Progress Indicator
    From Job ContextFrom Coroutine Execution Context - coroutineToIndicator() 1
    - @@ -371,8 +363,8 @@ blockingContext() enables ProgressManager.checkCanceled(), forwards modality state, etc. It has an opposite behavior to runBlockingCancellable(). - Since 2024.2, it is a no-operation function, as the blocking context was unified - with the suspending context into the Job context. + Since 2024.2, it is a no-operation function, as the Blocking Context was unified + with the Suspending Context into the Coroutine Execution Context.
    2 @@ -397,12 +389,12 @@

    It is only possible to:

    -
  • switch from the blocking context or progress indicator to the suspending context
    • -
  • switch from the suspending context to the blocking context
    • +
  • switch from the Blocking Context or Progress Indicator to the Suspending Context
    • +
  • switch from the Suspending Context to the Blocking Context
    •  -

    The lack of an API for switching from suspending and blocking contexts to progress indicator is +

    The lack of an API for switching from Suspending and Blocking contexts to the Progress Indicator is intentional. - Cancellable and trackable tasks should be run in coroutines as the progress indicator is obsolete since + Cancellable and trackable tasks should be run in coroutines as the Progress Indicator is obsolete since 2024.1.

    @@ -413,6 +405,6 @@ - +
    + To Suspending Context To Blocking Context To Progress Indicator