improve runInReadActionWithWriteActionPriority, add assertion (IDEA-CR-15454)

platform/core-api/src/com/intellij/openapi/progress/ProgressManager.java

@@ -234,6 +234,8 @@ public abstract class ProgressManager extends ProgressIndicatorProvider {
    * <li>action started to execute, but was aborted using {@link ProcessCanceledException} when some other thread initiated
    * write action</li>
    * </ul>
+   * If unable to run read action because of interfering write action, this method waits for that write action to complete.
+   * So under no circumstances must you call this method from read action or under critical locks.
    * @since 171.*
    */
   public abstract boolean runInReadActionWithWriteActionPriority(@NotNull final Runnable action);

platform/platform-impl/src/com/intellij/openapi/progress/impl/ProgressManagerImpl.java

@@ -159,6 +159,9 @@ public class ProgressManagerImpl extends CoreProgressManager implements Disposab
 
   @Override
   public boolean runInReadActionWithWriteActionPriority(@NotNull Runnable action) {
+    if (ApplicationManager.getApplication().isReadAccessAllowed()) {
+      throw new AssertionError("runInReadActionWithWriteActionPriority shouldn't be invoked from read action");
+    }
     boolean success = ProgressIndicatorUtils.runInReadActionWithWriteActionPriority(action);
     if (!success) {
       ProgressIndicatorUtils.yieldToPendingWriteActions();

platform/platform-impl/src/com/intellij/openapi/progress/util/ProgressIndicatorUtils.java

@@ -230,7 +230,7 @@ public class ProgressIndicatorUtils {
 
   /**
    * Ensure the current EDT activity finishes in case it requires many write actions, with each being delayed a bit
-   * by background thread read action (until its first checkCanceled call).
+   * by background thread read action (until its first checkCanceled call). Shouldn't be called from under read action.
    */
   public static void yieldToPendingWriteActions() {
     ApplicationManager.getApplication().invokeAndWait(EmptyRunnable.INSTANCE, ModalityState.any());