Changes in Threading Model in the IntelliJ Platform 2025.3

Announcements
,
1

Hello everyone!

We would like to share with you important updates of the threading model in the IntelliJ Platform 2025.3.

Our effort is concentrated on the adoption of background write actions. In this release, the following write actions were migrated to background:

  • VFS refresh. It means that “synchronizing file system changes” operation now runs in background threads. This can be disabled with the registry option vfs.refresh.use.background.write.action
  • Document commit. It means that the reparse of PSI trees after document modifications now could also happen in background. This can be disabled with the registry option document.async.commit.with.coroutines
  • Document saving on frame deactivation. This can be disabled with document.save.in.background.allowed

It does not automatically fix the UI freezes caused by the Read/Write lock on EDT, but it is a start. We are committed to continuing this effort. Write actions on the UI thread are supported as usual.

An important consequence of these changes is that they are conceptually incompatible with the IntelliJ Platform Test Framework based on JUnit3/4, where all tests run on EDT. Previously, all tests assumed that write actions are queued on EDT, so tests sometimes manually dispatched pending AWT events in order to await the result of some file modification. Currently, this invariant breaks – it is not enough to spin the AWT Event Queue to await write actions. If you think that your test hangs because of this change, then you can either migrate your test to background thread, or consider using com.intellij.testFramework.PlatformTestUtil#dispatchAllInvocationEventsInIdeEventQueue – this function was adapted to await all background write actions.

Other changes:

  • Editor models (caret, selection, folding, document) do not require read lock when accessed on EDT (IJPL-184084). Write action is still required for modification on both EDT and background threads. This change helps to avoid UI freezes during Swing repaint.
  • We are stabilizing function Dispatchers.UI. This is a UI thread coroutine dispatcher similar to Dispatchers.EDT, but with one important difference – Dispatchers.UI does not acquire write-intent lock, and it is forbidden to acquire the Read/Write lock inside it. Please use this dispatcher if you are working with pure UI.
  • We are stabilizing functions backgroundWriteAction and readAndBackgroundWriteAction. Their use might be limited currently because not all areas in the platform are ready for background execution though.
  • As IntelliJ Platform migrated to Java 21, we are experimenting with virtual threads. Feel free to explore com.intellij.concurrency.virtualThreads.IntelliJVirtualThreads and com.intellij.concurrency.virtualThreads.VirtualThreads#asyncAsVirtualThread and leave your feedback.
  • When the IDE is freezed on Read/Write lock, a freeze popup appears in the bottom of the screen. It helps to investigate the reason of freezes quicker.
5 Likes
2

Thank you @konstantin.nisht , updates like are highly appreciated and help to adapt to such changes early.

Is this related to calls to `PsiDocumentManager.commitDocument` (and related methods) by plugins?

It’s current documentation in intellij-community says:

* For documents with event-system-enabled PSI ({@link FileViewProvider#isEventSystemEnabled()}), should be called on EDT in
* a write-safe context (see {@link com.intellij.openapi.application.TransactionGuard}).

For 2025.3, should we still call commitDocument on the EDT and the platform takes care to move the reparse into a background thread or should plugins avoid committing documents on the EDT?

Thank you!

3

Hi Joachim,
We maintain full backward compatibility here, so if you do nothing with your plugin – nothing shall change for you. As of now, it is totally normal to commit documents on EDT, so no actions are required.
The docs are actually inconsistent here now, but I’d like to not change this paragraph in this release – it is a little early to publicly advertise such change in contract until we stabilize this new behavior.