Background-Capable VFS Listener APIs

Announcements
1

TL;DR: Watch a 2 min video explanation:

The IntelliJ Platform now offers background-capable variants for Virtual File System listener APIs. If your plugin watches many file events, these new hooks can help reduce UI freezes during heavy file operations.

What Existed Before

Classic bulk listeners

The traditional path used BulkFileListener subscribed to VirtualFileManager.VFS_CHANGES. Callbacks ran on the EDT inside a write-action, causing UI stalls during heavy file operations.

Old async listeners

AsyncFileListener already split work into prepareChange(...) (precompute) and appliers (beforeVfsChange() / afterVfsChange()). However, old registration via addAsyncFileListener(...) or extension point com.intellij.vfs.asyncListener had EDT-oriented applier execution.

What’s New

Four new API components are now available:

Old vs. New

Bulk listeners:

  • Old: BulkFileListener on VFS_CHANGES — EDT-oriented dispatch, write-action semantics
  • New: BulkFileListenerBackgroundable on VFS_CHANGES_BG — same write-action semantics, but thread may be background

Async listeners:

  • Old: addAsyncFileListener(...) / com.intellij.vfs.asyncListener — EDT-oriented applier handling
  • New: addAsyncFileListenerBackgroundable(...) / com.intellij.vfs.asyncListenerBackgroundable — background-capable applier execution

The key semantic shift: callbacks still happen under write-action constraints, but the thread is no longer guaranteed to be EDT.

Why It Matters

Heavy file-event analysis can now avoid EDT-oriented listener paths. This reduces UI pressure during indexing, refresh, and large branch switches.

Migration Considerations

If you consider migrating existing VFS listeners:

Important Caveats

These APIs are experimental and may change. Older IDE baselines may not have them at all. Plugins targeting multiple IDE versions will need compatibility strategies, either separate builds by baseline or runtime feature detection with fallback to legacy registration.

For implementation details, see the source code in platform/core-api/src/com/intellij/openapi/vfs/.

6 Likes