From be49f04479afc47c33526200195b918aa23edc4b Mon Sep 17 00:00:00 2001 From: Daniil Ovchinnikov Date: Tue, 5 Mar 2024 15:35:35 +0100 Subject: [PATCH] IJPL-384 IJPL-773 clarify obsolete progress-indicator-based APIs GitOrigin-RevId: 0fac85862339c8612b12d2c5827683c0f9950c2c --- .../openapi/progress/ProgressIndicator.java | 47 ++++++++ .../openapi/progress/ProgressManager.java | 105 +++++++++++++++++- .../com/intellij/openapi/progress/Task.java | 40 +++++-- 3 files changed, 183 insertions(+), 9 deletions(-) diff --git a/platform/core-api/src/com/intellij/openapi/progress/ProgressIndicator.java b/platform/core-api/src/com/intellij/openapi/progress/ProgressIndicator.java index bf022761efed..7448eb990e62 100644 --- a/platform/core-api/src/com/intellij/openapi/progress/ProgressIndicator.java +++ b/platform/core-api/src/com/intellij/openapi/progress/ProgressIndicator.java @@ -10,6 +10,53 @@ import static com.intellij.openapi.util.NlsContexts.ProgressDetails; import static com.intellij.openapi.util.NlsContexts.ProgressText; /** + *

Obsolescence notice

+ *

+ * This interface and its implementation are effectively obsolete. + * More info in the issue and linked issues and + * in the Knowledge Base. + * It's not marked with {@link ApiStatus.Obsolete} at the moment to avoid excessive highlighting everywhere. + *

+ *

+ * *

An object accompanying a computation, usually in a background thread. It allows displaying process status to the user * ({@link #setText}, {@link #setText2}, {@link #setFraction}, {@link #setIndeterminate}) and * interrupt if the computation is canceled ({@link #checkCanceled()}).

diff --git a/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java b/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java index 0f070e834111..fa34d6ba39b5 100644 --- a/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java +++ b/platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java @@ -11,7 +11,12 @@ import com.intellij.openapi.util.NlsContexts.ProgressText; import com.intellij.openapi.util.NlsContexts.ProgressTitle; import com.intellij.openapi.util.Ref; import com.intellij.openapi.util.ThrowableComputable; +import com.intellij.platform.util.progress.StepsKt; import com.intellij.util.concurrency.annotations.RequiresBlockingContext; +import kotlin.coroutines.Continuation; +import kotlin.jvm.functions.Function0; +import kotlin.jvm.functions.Function1; +import kotlin.jvm.functions.Function2; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.ApiStatus.Obsolete; import org.jetbrains.annotations.NotNull; @@ -48,19 +53,38 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { public abstract boolean hasUnsafeProgressIndicator(); /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + *

+ *

+ * * Runs the given process synchronously in calling thread, associating this thread with the specified progress indicator. * This means that it'll be returned by {@link ProgressManager#getProgressIndicator()} inside the {@code process}, * and {@link ProgressManager#checkCanceled()} will throw a {@link ProcessCanceledException} if the progress indicator is canceled. * * @param progress an indicator to use, {@code null} means reuse current progress. * The progress is {@link ProgressIndicator#start started} before running {@code process} and {@link ProgressIndicator#stop() stopped} afterward. - * - * @see CoroutinesKt#coroutineToIndicator */ @Obsolete public abstract void runProcess(@NotNull Runnable process, @Nullable ProgressIndicator progress) throws ProcessCanceledException; /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link #runProcess(Runnable, ProgressIndicator)} notice. + *

+ * * Performs the given computation synchronously in calling thread and returns its result, associating this thread with the specified progress indicator. * This means that it'll be returned by {@link ProgressManager#getProgressIndicator()} inside the {@code process}, * and {@link ProgressManager#checkCanceled()} will throw a {@link ProcessCanceledException} if the progress indicator is canceled. @@ -77,6 +101,27 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { return ref.get(); } + /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + *

+ *

+ */ @Obsolete @Override public abstract ProgressIndicator getProgressIndicator(); @@ -120,6 +165,16 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { public abstract T computeInNonCancelableSection(@NotNull ThrowableComputable computable) throws E; /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + *

    + *
  • Consider getting rid of a modal progress altogether, for example, by using a background progress,
    • + *
  • or use {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}
    • + *
  • or {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress}.
    • + *
+ * + *

* Runs the specified operation in a background thread and shows a modal progress dialog in the * main thread while the operation is executing. * If a dialog can't be shown (e.g. under write action or in headless environment), @@ -138,6 +193,11 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { @Nullable Project project); /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link #runProcessWithProgressSynchronously(Runnable, String, boolean, Project)} notice. + *

* Runs the specified operation in a background thread and shows a modal progress dialog in the * main thread while the operation is executing. * If a dialog can't be shown (e.g. under write action or in headless environment), @@ -157,6 +217,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { @Nullable Project project) throws E; /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link #runProcessWithProgressSynchronously(Runnable, String, boolean, Project)} notice. + *

+ * * Runs the specified operation in a background thread and shows a modal progress dialog in the * main thread while the operation is executing. * If a dialog can't be shown (e.g. under write action or in headless environment), @@ -200,6 +266,16 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { @NotNull PerformInBackgroundOption option); /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + *
+ * Do not use directly! + * Use {@link Task#queue()} instead of this method, or migrate the Task to coroutines. + * Please find appropriate replacements in the respective Task documentation: + * {@link Task.Backgroundable}, {@link Task.Modal}, {@link Task.WithResult}, {@link Task.ConditionalModal}. + *

+ * * Runs a specified {@code task} in either background/foreground thread and shows a progress dialog. * * @param task task to run (either {@link Task.Modal} or {@link Task.Backgroundable}). @@ -213,6 +289,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { public abstract void run(@NotNull Task task); /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link Task.WithResult} notice. + *

+ * * Runs a specified computation with a modal progress dialog. */ @Obsolete @@ -222,6 +304,13 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { return task.getResult(); } + /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link ProgressManager#run(Task)} notice. + *

+ */ @Obsolete public abstract void runProcessWithProgressAsynchronously(@NotNull Task.Backgroundable task, @NotNull ProgressIndicator progressIndicator); @@ -245,6 +334,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { } /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * See {@link #runProcess(Runnable, ProgressIndicator)} notice. + *

+ * * @param progress an indicator to use, {@code null} means reuse current progress * The methods {@link ProgressIndicator#start()} or {@link ProgressIndicator#stop()} are not called because it's assumed the {@code progress} is already running. */ @@ -264,6 +359,12 @@ public abstract class ProgressManager extends ProgressIndicatorProvider { } /** + *

Obsolescence notice

+ *

+ * See {@link ProgressIndicator} notice. + * Use {@link com.intellij.openapi.application.ReadAction#computeCancellable} instead. + *

+ * * This method attempts to run provided action synchronously in a read action, so that, if possible, it wouldn't impact any pending, * executing or future write actions (for this to work effectively the action should invoke {@link ProgressManager#checkCanceled()} or * {@link ProgressIndicator#checkCanceled()} often enough). diff --git a/platform/core-api/src/com/intellij/openapi/progress/Task.java b/platform/core-api/src/com/intellij/openapi/progress/Task.java index 4e20a6bd4002..7a479ccff0d0 100644 --- a/platform/core-api/src/com/intellij/openapi/progress/Task.java +++ b/platform/core-api/src/com/intellij/openapi/progress/Task.java @@ -15,6 +15,8 @@ import com.intellij.openapi.util.text.StringUtil; import com.intellij.util.ExceptionUtil; import com.intellij.util.ObjectUtils; import com.intellij.util.concurrency.annotations.RequiresBlockingContext; +import kotlin.coroutines.Continuation; +import kotlin.jvm.functions.Function2; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.ApiStatus.Obsolete; import org.jetbrains.annotations.NotNull; @@ -24,6 +26,7 @@ import javax.swing.*; /** *

Obsolescence notice

+ * See {@link ProgressIndicator} notice. * Use one of the following functions to run tasks: *
    *
  • {@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress}
    • @@ -203,7 +206,11 @@ public abstract class Task implements TaskInfo, Progressive { } /** - * @see com.intellij.openapi.progress.TasksKt#withBackgroundProgress + *

    Obsolescence notice

    + *

    + * See {@link ProgressIndicator} notice. + * Use {@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress}. + *

    */ @Obsolete public abstract static class Backgroundable extends Task implements PerformInBackgroundOption { @@ -257,8 +264,14 @@ public abstract class Task implements TaskInfo, Progressive { } /** - * @see com.intellij.openapi.progress.TasksKt#withModalProgress - * @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking + *

    Obsolescence notice

    + *

    + * See {@link ProgressIndicator} notice. + *

      + *
    • Use {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress},
      • + *
    • or {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}.
      • + *
    + *

    */ @Obsolete public abstract static class Modal extends Task { @@ -278,9 +291,15 @@ public abstract class Task implements TaskInfo, Progressive { } /** - * @see com.intellij.openapi.progress.TasksKt#withBackgroundProgress - * @see com.intellij.openapi.progress.TasksKt#withModalProgress - * @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking + *

    Obsolescence notice

    + *

    + * See {@link ProgressIndicator} notice. + *

      + *
    • Use {@link com.intellij.platform.ide.progress.TasksKt#withBackgroundProgress},
      • + *
    • {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress},
      • + *
    • or {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking}.
      • + *
    + *

    */ @Obsolete public abstract static class ConditionalModal extends Backgroundable { @@ -345,7 +364,14 @@ public abstract class Task implements TaskInfo, Progressive { } /** - * @see com.intellij.openapi.progress.TasksKt#runWithModalProgressBlocking + *

    Obsolescence notice

    + *

    + * See {@link ProgressIndicator} notice. + *

      + *
    • Use {@link com.intellij.platform.ide.progress.TasksKt#runWithModalProgressBlocking},
      • + *
    • or {@link com.intellij.platform.ide.progress.TasksKt#withModalProgress}.
      • + *
    + *

    */ @Obsolete public abstract static class WithResult extends Task.Modal {