[llvm] 4e171c9 - [NFC][NewPM] Add clarification on analysis manager proxies

[Arthur Eubanks via llvm-commits]

Author: Arthur Eubanks
Date: 2020-07-22T08:41:20-07:00
New Revision: 4e171c9f19d49dbe1d02611f208f0d59732f5496

URL: https://github.com/llvm/llvm-project/commit/4e171c9f19d49dbe1d02611f208f0d59732f5496
DIFF: https://github.com/llvm/llvm-project/commit/4e171c9f19d49dbe1d02611f208f0d59732f5496.diff

LOG: [NFC][NewPM] Add clarification on analysis manager proxies

Explain why you can only get a cached analysis result, not compute one
on the fly.

Reviewed By: asbirlea

Differential Revision: https://reviews.llvm.org/D84259

Added: 
    

Modified: 
    llvm/include/llvm/IR/PassManager.h

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/IR/PassManager.h b/llvm/include/llvm/IR/PassManager.h
index f503871e2360..c2f535037a56 100644
--- a/llvm/include/llvm/IR/PassManager.h
+++ b/llvm/include/llvm/IR/PassManager.h
@@ -1061,7 +1061,16 @@ extern template class InnerAnalysisManagerProxy<FunctionAnalysisManager,
 ///
 /// This proxy only exposes the const interface of the outer analysis manager,
 /// to indicate that you cannot cause an outer analysis to run from within an
-/// inner pass.  Instead, you must rely on the \c getCachedResult API.
+/// inner pass.  Instead, you must rely on the \c getCachedResult API.  This is
+/// due to keeping potential future concurrency in mind. To give an example,
+/// running a module analysis before any function passes may give a 
diff erent
+/// result than running it in a function pass. Both may be valid, but it would
+/// produce non-deterministic results. GlobalsAA is a good analysis example,
+/// because the cached information has the mod/ref info for all memory for each
+/// function at the time the analysis was computed. The information is still
+/// valid after a function transformation, but it may be *
diff erent* if
+/// recomputed after that transform. GlobalsAA is never invalidated.
+
 ///
 /// This proxy doesn't manage invalidation in any way -- that is handled by the
 /// recursive return path of each layer of the pass manager.  A consequence of