Progress system

IntelliJ's progress is a tool for controlling long-running operations. This may mean:

• Displaying a dialog box with a progress bar while the operation is running.
• Allowing user to cancel the operation.
• Allowing the operation to update the text and completion percentage as it runs.
• Associating background tasks with a Disposable, so they get cancelled when e.g. a dialog or the whole project is closed.
• Running a long operation on the UI thread (with the write lock held), while still pumping AWT messages from time to time.

Start by reading the official docs on the subject, see below for more in-depth details.

Progress Indicator

ProgressIndicator is an object that allows the task and whoever started it to exchange information. A task should generally work with any ProgressIndicator and it's the job of the caller to pick the right indicator and run tasks using it.

The task should call checkCancelled() from time to time, which will throw a ProcessCanceledException if the task has indeed been cancelled. ProcessCanceledException is not considered a crash by the IDE, so you don‘t have to catch it and should avoid wrapping it in RuntimeException, ExecutionException or UncheckedExecutionException. If you do catch it, finish what you’re doing quickly and avoid running for a long time after your task has been cancelled.

The progress indicator to use may be passed to you from the caller, but it can also be implicit for a given thread. That‘s why the most common way of checking for cancellation is calling the static method ProgressManager.checkCancelled(). This is what most PSI methods do, so just doing anything with PSI means you’re already using the progress system.

By default the IDE cancels certain operations if they take too long, e.g. code completion. If you want to disable this for debugging, use the “Disable ProcessCanceledException” internal action.

You can look at checkCancelled as a form of cooperative multitasking: your thread gives the IDE a chance to either throw an exception (effectively freeing the OS thread to do other things) or execute other maintenance operations. This is how the UI gets updated during long-running refactorings that otherwise would block the UI thread (see PotemkinProgress) or how the IDE prioritizes some threads by parking all other threads (see ProgressManagerImpl#sleepIfNeededToGivePriorityToAnotherThread).

Useful indicator implementations:

• EmptyProgressIndicator
• ProgressWindow, but most likely this can be handled by ProgressManager (see below).
• SmoothProgressAdapter, typically used with ProgressWindow.

Progress manager

ProgressManager is an application service used to “run tasks under progress” and manage progress indicators.

The most basic entry point is runProcess which makes the IDE aware of the task and allows you to choose a custom progress indicator. The benefit of using it is that the IDE will ask the user for confirmation if they try to close the IDE while a task is still running.

A common use case is running a task in a background thread, with a responsive modal dialog in the foreground. This is done by calling runProcessWithProgressSynchronously and is the easiest way of moving expensive operations off the UI thread. Of course, the modal dialog prevents the user from doing anything, so it's only a bit better than freezing the UI. The best way to compute something in the background (if possible) is to use runProcessWithProgressAsynchronously and consider if the progress UI should start minimized.

Note that ProgressManager has two equivalent APIs: you can either call runProcessWithProgress{Synchronously,Asynchronously} or create your own Task objects (Task.Modal or Task.Backgroundable) and pass them to run, which is equivalent. There are also some Kotlin extensions, like runBackgroundableTask.

Note that for runProcessWithProgressSynchronously and run(Task.Modal):

• The call blocks the current thread.
• The call runs the task in a non-EDT thread while showing a progress bar.
• If called from the EDT, EDT events will still be processed (from within the call) while the call blocks.
• Write actions within the task must still be sent back to run on the EDT, and these will still freeze the UI. The progress bar UI does not update and the cancel button does not get checked while a write action is running, even if you call checkCanceled() frequently.
• Outside write actions, the IDE and progress bar update as expected; the IDE window can even be resized, updating properly.
• This option might work well if you can do many write actions, one after the other; the PSI is unlikely to have changed in between write actions because there is a modal dialog.

If you want to do one long write action (rather than many small write actions) without completely freezing the UI, an alternative option is ApplicationManagerEx.getApplicationEx().runWriteActionWithCancellableProgressInDispatchThread.

• The method is marked @ApiStatus.Experimental but is used in a few refactorings, and the implementation uses PotemkinProgress, which is not experimental.
• The method blocks and runs the write action on the EDT, showing a special progress bar (PotemkinProgress) that paints itself and handles cancel button events, as long as the action calls checkCanceled() periodically. No other Swing events are handled.
• During the write action, the IDE is not redrawn properly (e.g. if resized).
• In the future, we might see work continue on idea.disable.implicit.read.on.edt, which would presumably mean PSI writes could be done from any thread and so might allow for long write actions that don't freeze the UI.

Another piece of functionality available in ProgressManager is running a potentially long read action under a progress indicator that will get cancelled whenever there's a pending write action, which means the action should be able to recover from earlier failures and the caller needs to keep submitting it in a loop. The benefit is that write lock is not blocked, so write operations like typing are more responsive. There are a few APIs in IntelliJ that let you do this, and they all end up calling the same code that is based on the progress system and assumes the task will call checkCancelled often enough:

• ProgressManager.runInReadActionWithWriteActionPriority
• ReadAction.nonBlocking combined with NonBlockingReadAction.submit. This API handles rescheduling, so is preferable.
• ProgressIndicatorUtils.runInReadActionWithWritePriority and ProgressIndicatorUtils.scheduleWithWriteActionPriority (for running on EDT). This is what other APIs call into.

If you'd like to play with non-blocking read action, you can use this code as template. This can be registered as an internal action to execute and you should see the action cancelled as you try typing in the editor:

package com.android.tools.idea.actions

import com.intellij.openapi.actionSystem.AnAction
import com.intellij.openapi.actionSystem.AnActionEvent
import com.intellij.openapi.application.ReadAction
import com.intellij.openapi.diagnostic.Logger
import com.intellij.openapi.progress.ProgressManager
import com.intellij.util.concurrency.AppExecutorUtil

private val LOG = Logger.getInstance(TryNonBlockingReadAction::class.java)

/**
 * Use by adding this to android-plugin.xml:
 * `<action internal="true" id="Android.TryNonBlockingReadAction" class="com.android.tools.idea.actions.TryNonBlockingReadAction"/`
 */
class TryNonBlockingReadAction : AnAction("Start a long non-blocking read action") {
  override fun actionPerformed(e: AnActionEvent) {
    ReadAction.nonBlocking {
      try {
        LOG.info("TryNonBlockingReadAction starting")
        repeat(1000) {
          ProgressManager.checkCanceled()
          Thread.sleep(10)
          LOG.info("TryNonBlockingReadAction running on ${Thread.currentThread().name}")
        }
      }
      finally {
        LOG.info("TryNonBlockingReadAction stack unwinding.")
      }
    }.submit(AppExecutorUtil.getAppExecutorService())
      .onSuccess { LOG.info("success") }
      .onError { t -> LOG.info("error: ${t::class.java.name}") }
  }
}

Other related APIs

BackgroundTaskUtil contains methods for executing a piece of code, synchronously or on a pooled thread, under a progress indicator tied to a given Disposable, which means the indicator (and thus the task itself) gets cancelled when the Disposable is disposed.