Package com.intellij.openapi.project

Class DumbService

java.lang.Object

com.intellij.openapi.project.DumbService

Direct Known Subclasses:

DumbServiceImpl, MockDumbService

public abstract class DumbService
extends java.lang.Object

A service managing the IDE's 'dumb' mode: when indexes are updated in the background, and the functionality is very much limited. Only the explicitly allowed functionality is available. Usually, it's allowed by implementing DumbAware interface.

"Dumb" mode starts and ends in a WriteAction, so if you're inside a ReadAction on a background thread, it won't suddenly begin in the middle of your operation. But note that whenever you start a top-level read action on a background thread, you should be prepared to anything being changed, including "dumb" mode being suddenly on and off. To avoid executing a read action in "dumb" mode, please use runReadActionInSmartMode(com.intellij.openapi.util.Computable<T>) or NonBlockingReadAction.inSmartMode(com.intellij.openapi.project.Project).

More information about dumb mode could be found here: IndexNotReadyException

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DumbService.DumbModeListener

Field Summary

Fields

Modifier and Type	Field and Description
static Topic<DumbService.DumbModeListener>	DUMB_MODE

Constructor Summary

Constructors

Constructor and Description
DumbService()

Method Summary

Modifier and Type	Method and Description
static void	allowStartingDumbModeInside(DumbModePermission permission, java.lang.Runnable runnable) Deprecated. Obsolete, does nothing, just executes the passed runnable.
abstract void	cancelAllTasksAndWait() Cancels all tasks and wait when their execution is finished.
abstract void	cancelTask(DumbModeTask task) Cancels the given task.
abstract void	completeJustSubmittedTasks() Runs the "just submitted" tasks under a modal dialog.
<T,E extends java.lang.Throwable> T	computeWithAlternativeResolveEnabled(ThrowableComputable<T,E> runnable) Invokes the given computable with alternative resolve set to true.
<T> java.util.List<T>	filterByDumbAwareness(java.util.Collection<? extends T> collection)
<T> java.util.List<T>	filterByDumbAwareness(T [] array)
static <T> java.util.List<T>	getDumbAwareExtensions(Project project, ExtensionPointName<T> extensionPoint)
static <T> java.util.List<T>	getDumbAwareExtensions(Project project, ProjectExtensionPointName<T> extensionPoint)
static DumbService	getInstance(Project project)
abstract ModificationTracker	getModificationTracker() The tracker is advanced each time we enter/exit from dumb mode.
abstract Project	getProject()
abstract boolean	isAlternativeResolveEnabled()
abstract boolean	isDumb() To avoid race conditions use it only in EDT thread or inside read-action.
static boolean	isDumb(Project project)
static boolean	isDumbAware(java.lang.Object o)
abstract boolean	isSuspendedDumbMode() Checks whether isDumb() is true for the current project and if it's currently suspended by user or a suspendIndexingAndRun(java.lang.String, java.lang.Runnable) call.
void	makeDumbAware(javax.swing.JComponent componentToDisable, Disposable parentDisposable) Disables given component temporarily during dumb mode.
abstract void	queueTask(DumbModeTask task) Queues a task to be executed in "dumb mode", where access to indexes is forbidden.
void	repeatUntilPassesInSmartMode(java.lang.Runnable r) Deprecated. This method provides no guarantees and should be avoided, please use runReadActionInSmartMode(com.intellij.openapi.util.Computable<T>) instead.
<T> T	runReadActionInSmartMode(Computable<T> r) Pause the current thread until dumb mode ends, and then run the read action.
void	runReadActionInSmartMode(java.lang.Runnable r) Pause the current thread until dumb mode ends, and then run the read action.
abstract void	runWhenSmart(java.lang.Runnable runnable) Executes the runnable as soon as possible on AWT Event Dispatch when: project is initialized and there's no dumb mode in progress This may also happen immediately if these conditions are already met. Note that it's not guaranteed that the dumb mode won't start again during this runnable execution, it should manage that situation explicitly.
<E extends java.lang.Throwable> void	runWithAlternativeResolveEnabled(ThrowableRunnable<E> runnable) Invokes the given runnable with alternative resolve set to true.
abstract void	setAlternativeResolveEnabled(boolean enabled) Deprecated. Use runWithAlternativeResolveEnabled(ThrowableRunnable) or computeWithAlternativeResolveEnabled(ThrowableComputable) or withAlternativeResolveEnabled(Runnable) instead
abstract boolean	showDumbModeDialog(java.util.List<java.lang.String> actionNames) Show modal progress about indexing blocking those actions until it is cancelled or indexing stops.
abstract void	showDumbModeNotification(java.lang.String message) Show a notification when given action is not available during dumb mode.
abstract void	smartInvokeLater(java.lang.Runnable runnable) Invoke the runnable later on EventDispatchThread AND when IDE isn't in dumb mode.
abstract void	smartInvokeLater(java.lang.Runnable runnable, ModalityState modalityState) Invoke the runnable later on EventDispatchThread with the given modality state AND when IDE isn't in dumb mode.
abstract void	suspendIndexingAndRun(java.lang.String activityName, java.lang.Runnable activity) Runs a heavy activity and suspends indexing (if any) for this time.
<T> T	tryRunReadActionInSmartMode(Computable<T> task, java.lang.String notification)
abstract void	unsafeRunWhenSmart(java.lang.Runnable runnable)
abstract void	waitForSmartMode() Pause the current thread until dumb mode ends and then continue execution.
void	withAlternativeResolveEnabled(java.lang.Runnable runnable) Invokes the given runnable with alternative resolve set to true.
abstract javax.swing.JComponent	wrapGently(javax.swing.JComponent dumbUnawareContent, Disposable parentDisposable) Replaces given component temporarily with "Not available until indices are built" label during dumb mode.
abstract javax.swing.JComponent	wrapWithSpoiler(javax.swing.JComponent dumbAwareContent, java.lang.Runnable updateRunnable, Disposable parentDisposable) Adds a "Results might be incomplete while indexing." decorator to a given component during dumb mode.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DUMB_MODE

public static final Topic<DumbService.DumbModeListener> DUMB_MODE

See Also:

ComponentManager.getMessageBus()

Constructor Detail

DumbService

public DumbService()

Method Detail

getModificationTracker

public abstract ModificationTracker getModificationTracker()

The tracker is advanced each time we enter/exit from dumb mode.

isDumb

public abstract boolean isDumb()

To avoid race conditions use it only in EDT thread or inside read-action. See documentation for this class DumbService

Returns:

whether the IDE is in dumb mode, which means that right now indexes are updated in the background. The IDE offers only limited functionality at such times, e.g., plain text file editing and version control operations.

isDumb

public static boolean isDumb(Project project)

getDumbAwareExtensions

public static <T> java.util.List<T> getDumbAwareExtensions(Project project,
                                                           ExtensionPointName<T> extensionPoint)

getDumbAwareExtensions

public static <T> java.util.List<T> getDumbAwareExtensions(Project project,
                                                           ProjectExtensionPointName<T> extensionPoint)

runWhenSmart

public abstract void runWhenSmart(java.lang.Runnable runnable)

Executes the runnable as soon as possible on AWT Event Dispatch when:

• project is initialized
• and there's no dumb mode in progress

This may also happen immediately if these conditions are already met.

Note that it's not guaranteed that the dumb mode won't start again during this runnable execution, it should manage that situation explicitly.

waitForSmartMode

public abstract void waitForSmartMode()

Pause the current thread until dumb mode ends and then continue execution. NOTE: there are no guarantees that a new dumb mode won't begin before the next statement. Hence: use with care. Consider using runWhenSmart(Runnable) or runReadActionInSmartMode(Runnable) instead

runReadActionInSmartMode

public <T> T runReadActionInSmartMode(Computable<T> r)

Pause the current thread until dumb mode ends, and then run the read action. Indexes are guaranteed to be available inside that read action, unless this method is already called with read access allowed.

Throws:

ProcessCanceledException - if the project is closed during dumb mode

tryRunReadActionInSmartMode

public <T> T tryRunReadActionInSmartMode(Computable<T> task,
                                         java.lang.String notification)

runReadActionInSmartMode

public void runReadActionInSmartMode(java.lang.Runnable r)

Pause the current thread until dumb mode ends, and then run the read action. Indexes are guaranteed to be available inside that read action, unless this method is already called with read access allowed.

Throws:

ProcessCanceledException - if the project is closed during dumb mode

repeatUntilPassesInSmartMode

@Deprecated
public void repeatUntilPassesInSmartMode(java.lang.Runnable r)

Deprecated. This method provides no guarantees and should be avoided, please use runReadActionInSmartMode(com.intellij.openapi.util.Computable<T>) instead.

Pause the current thread until dumb mode ends, and then attempt to execute the runnable. If it fails due to another dumb mode having started, try again until the runnable can complete successfully.

smartInvokeLater

public abstract void smartInvokeLater(java.lang.Runnable runnable)

Invoke the runnable later on EventDispatchThread AND when IDE isn't in dumb mode. The runnable won't be invoked if the project is disposed during dumb mode.

smartInvokeLater

public abstract void smartInvokeLater(java.lang.Runnable runnable,
                                      ModalityState modalityState)

Invoke the runnable later on EventDispatchThread with the given modality state AND when IDE isn't in dumb mode. The runnable won't be invoked if the project is disposed during dumb mode.

getInstance

public static DumbService getInstance(Project project)

filterByDumbAwareness

public <T> java.util.List<T> filterByDumbAwareness(T [] array)

Returns:

all the elements of the given array if there's no dumb mode currently, or the dumb-aware ones if isDumb() is true.

See Also:

isDumbAware(Object)

filterByDumbAwareness

public <T> java.util.List<T> filterByDumbAwareness(java.util.Collection<? extends T> collection)

Returns:

all the elements of the given collection if there's no dumb mode currently, or the dumb-aware ones if isDumb() is true.

See Also:

isDumbAware(Object)

queueTask

public abstract void queueTask(DumbModeTask task)

Queues a task to be executed in "dumb mode", where access to indexes is forbidden. Tasks are executed sequentially in background unless completeJustSubmittedTasks() is called in the same dispatch thread activity.

Tasks can specify custom "equality" policy via their constructor. Calling this method has no effect if an "equal" task is already enqueued (but not yet running).

cancelTask

public abstract void cancelTask(DumbModeTask task)

Cancels the given task. If it's in the queue, it won't be executed. If it's already running, its ProgressIndicator is canceled, so the next ProgressManager.checkCanceled() call will throw ProcessCanceledException.

cancelAllTasksAndWait

public abstract void cancelAllTasksAndWait()

Cancels all tasks and wait when their execution is finished. Should be called on write thread.

completeJustSubmittedTasks

public abstract void completeJustSubmittedTasks()

Runs the "just submitted" tasks under a modal dialog. "Just submitted" means that tasks were queued for execution earlier within the same Swing event dispatch thread event processing, and there were no other tasks already running at that moment. Otherwise, this method does nothing.

This functionality can be useful in refactorings (invoked in "smart mode"), when after VFS or root changes (which could start "dumb mode") some reference resolve is required (which again requires "smart mode").

Should be invoked on dispatch thread. It's the caller's responsibility to invoke this method only when the model is in internally consistent state, so that background threads with read actions don't see half-baked PSI/VFS/etc.

wrapGently

public abstract javax.swing.JComponent wrapGently(javax.swing.JComponent dumbUnawareContent,
                                                  Disposable parentDisposable)

Replaces given component temporarily with "Not available until indices are built" label during dumb mode.

Returns:

Wrapped component.

wrapWithSpoiler

public abstract javax.swing.JComponent wrapWithSpoiler(javax.swing.JComponent dumbAwareContent,
                                                       java.lang.Runnable updateRunnable,
                                                       Disposable parentDisposable)

Adds a "Results might be incomplete while indexing." decorator to a given component during dumb mode.

Parameters:

dumbAwareContent - - a component to wrap

updateRunnable - - an action to execute when dumb mode state changed or user explicitly request reload panel

Returns:

Wrapped component.

makeDumbAware

public void makeDumbAware(javax.swing.JComponent componentToDisable,
                          Disposable parentDisposable)

Disables given component temporarily during dumb mode.

showDumbModeNotification

public abstract void showDumbModeNotification(java.lang.String message)

Show a notification when given action is not available during dumb mode.

showDumbModeDialog

public abstract boolean showDumbModeDialog(java.util.List<java.lang.String> actionNames)

Show modal progress about indexing blocking those actions until it is cancelled or indexing stops.

Returns:

true if indexing stopped, and the dialog was not cancelled.

getProject

public abstract Project getProject()

isDumbAware

public static boolean isDumbAware(java.lang.Object o)

setAlternativeResolveEnabled

@Deprecated
public abstract void setAlternativeResolveEnabled(boolean enabled)

Deprecated. Use runWithAlternativeResolveEnabled(ThrowableRunnable) or computeWithAlternativeResolveEnabled(ThrowableComputable) or withAlternativeResolveEnabled(Runnable) instead

Enables or disables alternative resolve strategies for the current thread.

Normally reference resolution uses indexes, and hence is not available in dumb mode. In some cases, alternative ways of performing resolve are available, although much slower. It's impractical to always use these ways because it'll lead to overloaded CPU (especially given there's also indexing in progress). But for some explicit user actions (e.g., explicit Goto Declaration) turning on these slower methods is beneficial.

NOTE: even with alternative resolution enabled, methods like resolve(), findClass() etc may still throw IndexNotReadyException. So alternative resolve is not a panacea, it might help provide navigation in some cases but not in all.

A typical usage would involve try-finally, where the alternative resolution is first enabled, then an action is performed, and then alternative resolution is turned off in the finally block.

withAlternativeResolveEnabled

public void withAlternativeResolveEnabled(java.lang.Runnable runnable)

Invokes the given runnable with alternative resolve set to true.

See Also:

setAlternativeResolveEnabled(boolean)

computeWithAlternativeResolveEnabled

public <T,E extends java.lang.Throwable> T computeWithAlternativeResolveEnabled(ThrowableComputable<T,E> runnable)
                                                                         throws E extends java.lang.Throwable

Invokes the given computable with alternative resolve set to true.

Throws:

E extends java.lang.Throwable

See Also:

setAlternativeResolveEnabled(boolean)

runWithAlternativeResolveEnabled

public <E extends java.lang.Throwable> void runWithAlternativeResolveEnabled(ThrowableRunnable<E> runnable)
                                                                      throws E extends java.lang.Throwable

Invokes the given runnable with alternative resolve set to true.

Throws:

E extends java.lang.Throwable

See Also:

setAlternativeResolveEnabled(boolean)

isAlternativeResolveEnabled

public abstract boolean isAlternativeResolveEnabled()

Returns:

whether alternative resolution is enabled for the current thread.

See Also:

setAlternativeResolveEnabled(boolean)

allowStartingDumbModeInside

@Deprecated
public static void allowStartingDumbModeInside(DumbModePermission permission,
                                               java.lang.Runnable runnable)

Deprecated. Obsolete, does nothing, just executes the passed runnable.

See Also:

completeJustSubmittedTasks()

suspendIndexingAndRun

public abstract void suspendIndexingAndRun(java.lang.String activityName,
                                           java.lang.Runnable activity)

Runs a heavy activity and suspends indexing (if any) for this time. The user still can manually pause and resume the indexing. In that case, indexing won't be resumed automatically after the activity finishes.

Parameters:

activityName - the text (a noun phrase) to display as a reason for the indexing being paused

isSuspendedDumbMode

public abstract boolean isSuspendedDumbMode()

Checks whether isDumb() is true for the current project and if it's currently suspended by user or a suspendIndexingAndRun(java.lang.String, java.lang.Runnable) call. This should be called inside read action. The momentary system state is returned: there are no guarantees that the result won't change in the next line of the calling code.

unsafeRunWhenSmart

public abstract void unsafeRunWhenSmart(java.lang.Runnable runnable)