[LL FIR] reduce number of in-block modifications

The idea of optimization is simple – delay in-block modification
until the end of a write action.

Q: Why the end of write action?
A: We have to publish the result of modification somewhere during
write action to be sure that the next read action will see the
updated result. We can't publish the result somewhere later
because we can't guarantee that the modification will be visible
to all customers.

In the case of out-of-block modification, we still have to publish
the result immediately because it is hard to evaluate the consequences
of the opposite decision yet.

If an out-of-block modification happens, we can drop all previous
in-block modifications from the queue because they don't make sense
due to invalidation of the entire KtModule.

A corner case is the analysis under write action. The delay means that
there is no longer any guarantee that all PSI changes will be reflected
into FIR tree immediately. So now we can guaranty only that at
the start of `analyze` block you will have the up-to-date FIR tree.

^KT-60611 Fixed

analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/lifetime/KtReadActionConfinementLifetimeToken.kt

@@ -111,6 +111,29 @@ public inline fun <T> allowAnalysisOnEdt(action: () -> T): T {
  * Analysis is not supposed to be called from write action.
  * Such actions can lead to IDE freezes and incorrect behavior in some cases.
  *
+ * There is no guarantee that PSI changes will be reflected in an Analysis API world inside
+ * one [analyze] session.
+ * Example:
+ * ```
+ * // code to be analyzed
+ * fun foo(): Int = 0
+ *
+ * // use case code
+ * fun useCase() {
+ *   analyse(function) {
+ *    // 'getConstantFromExpressionBody' is an imaginary function
+ *    val valueBefore = function.getConstantFromExpressionBody() // valueBefore is 0
+ *
+ *    changeExpressionBodyTo(1) // now function will looks like `fun foo(): Int = 1`
+ *    val valueAfter = function.getConstantFromExpressionBody() // Wrong way: valueAfter is not guarantied to be '1'
+ *   }
+ *
+ *   analyse(function) {
+ *    val valueAfter = function.getConstantFromExpressionBody() // OK: valueAfter is guarantied to be '1'
+ *   }
+ * }
+ * ```
+ *
  * @see KtAnalysisSession
  * @see KtReadActionConfinementLifetimeToken
  */