Workbench concurrency support

We've seen that the JFace UI framework provides basic support for showing task progress in a dialog (see Long running operations for details). In Concurrency infrastructure, we reviewed the platform runtime support for concurrency and long running operations. Now we will look at how the platform UI enhances this infrastructure in the org.eclipse.ui.progress package. This package supplies the UI for showing job progress in the workbench and defines additional support for jobs that run in the UI thread.

First, let's look at the different kinds of background operations that may be running and how they are shown in the workbench UI:

Given an environment where several things may be happening at the same time, a user needs the following:

Progress service

The workbench progress service (IProgressService) is the primary interface to the workbench progress support. It can be obtained from the workbench and then used to show progress for both background operations and operations that run in the UI thread. The main purpose of this class is to provide one-stop shopping for running operations, removing the need for plug-in developers to decide what mechanism should be used for showing progress in a given situation. Another advantage is that the progress dialog shown with these methods provides good support for indicating when an operation is blocked by another and gives the user control to resolve the conflict. Where possible, long running operations should be run using IProgressService#busyCursorWhile:

   IProgressService progressService = PlatformUI.getWorkbench().getProgressService();
   progressService.busyCursorWhile(new IRunnableWithProgress(){
      public void run(IProgressMonitor monitor) {
         //do non-UI work

This method will initially put up a busy cursor, and replace it with a progress dialog if the operation lasts longer than a specified time threshhold. The advantage of this method over using a progress dialog is that the progress dialog won't be shown if the operation is short running . If your operation must update the UI, you can always use Display.asyncExec or Display.syncExec to run the code that modifies the UI.

If an operation must be run in its entirety in the UI thread, then IProgressService#runInUI should be used. This method will also display a progress dialog if the operation is blocked and give the user control.

      new IRunnableWithProgress() {
         public void run(IProgressMonitor monitor) {
            //do UI work

The third parameter can be null, or a scheduling rule for the operation. In this example, we are specifying the workspace root which will essentially lock the workspace while this UI operation is run.

You can also register an icon for a job family with the progress service so that the progress view can show the icon next to the running job. Here is an example that shows how the auto-build job family is associated with its icon:

   IProgressService service = PlatformUI.getWorkbench().getProgressService();
   ImageDescriptor newImage = IDEInternalWorkbenchImages.getImageDescriptor(
   service.registerIconForFamily(newImage, ResourcesPlugin.FAMILY_MANUAL_BUILD);
   service.registerIconForFamily(newImage, ResourcesPlugin.FAMILY_AUTO_BUILD);

Showing that a part is busy

IWorkbenchSiteProgressService includes API for scheduling jobs that change the appearance of a workbench part while the job is running. If your plug-in is running background operations that affect the state of a part, you can schedule the job via the part and the user will get feedback that the part is busy. Here is an example:

   IWorkbenchSiteProgressService siteService =
   siteService.schedule(job, 0 /* now */, true /* use the half-busy cursor in the part */);

Progress Properties for Jobs

The workbench defines progress-related properties for jobs in IProgressConstants . These can be used to control how a job is shown in the progress view. These can be used to tell the progress view to keep (IProgressConstants#KEEP_PROPERTY) your job in the view after it has finished, or only keep one (IProgressConstants#KEEPONE_PROPERTY) job at a time in the view. You can also associate an action (IProgressConstants#ACTION_PROPERTY) with a job. When a job has an associated action, the progress view shows a hyperlink so that a user can run the action. You can also find out if a user job is currently being shown in a progress dialog (IProgressConstants#PROPERTY_IN_DIALOG). A hint is provided in the bottom right of the status line when an action is available. The following example uses these properties:

   Job job = new Job("Do Work") {
      public IStatus run(IProgressMonitor monitor) {
         // do some work.  
         // Keep the finished job in the progress view only if it is not running in the progress dialog
         Boolean inDialog = (Boolean)getProperty(IProgressConstants.PROPERTY_IN_DIALOG);
            setProperty(IProgressConstants.KEEP_PROPERTY, Boolean.TRUE);
   job.setProperty(IProgressConstants.ICON_PROPERTY, Plugin.getImageDescriptor(WORK_IMAGE));
   IAction gotoAction = new Action("Results") {
      public void run() {
         // show the results
   job.setProperty(IProgressConstants.ACTION_PROPERTY, gotoAction);

Workbench jobs

Where possible, long running operations should be performed outside of the UI thread. However, this cannot always be avoided when the operation's purpose is to update the UI. SWT threading issues explains how this can be done using the SWT Display. The workbench defines a special job, UIJob, whose run method runs inside an SWT asyncExec. Subclasses of UIJob should implement the method runInUIThread instead of the run method.

WorkbenchJob extends UIJob so that the job can only be scheduled or run when the workbench is running. As always, you should avoid excessive work in the UI thread because the UI will not refresh for the duration of the UI Job.