[PM/AA] Cleanup comments, formatting, and organization of the AA
authorChandler Carruth <chandlerc@gmail.com>
Wed, 22 Jul 2015 23:16:02 +0000 (23:16 +0000)
committerChandler Carruth <chandlerc@gmail.com>
Wed, 22 Jul 2015 23:16:02 +0000 (23:16 +0000)
interface prior to making more substantial and invasive changes.

No functionality changed, and should hopefully keep subsequent patches
as clean and focused as possible in addition to making the comments and
such more clear.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@242964 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/Analysis/AliasAnalysis.h

index 42ae4d3..8725429 100644 (file)
@@ -191,70 +191,71 @@ public:
   uint64_t getTypeStoreSize(Type *Ty);
 
   //===--------------------------------------------------------------------===//
-  /// Alias Queries...
-  ///
+  /// \name Alias Queries
+  /// @{
 
-  /// alias - The main low level interface to the alias analysis implementation.
+  /// The main low level interface to the alias analysis implementation.
   /// Returns an AliasResult indicating whether the two pointers are aliased to
-  /// each other.  This is the interface that must be implemented by specific
+  /// each other. This is the interface that must be implemented by specific
   /// alias analysis implementations.
   virtual AliasResult alias(const MemoryLocation &LocA,
                             const MemoryLocation &LocB);
 
-  /// alias - A convenience wrapper.
-  AliasResult alias(const Value *V1, uint64_t V1Size,
-                    const Value *V2, uint64_t V2Size) {
+  /// A convenience wrapper around the primary \c alias interface.
+  AliasResult alias(const Value *V1, uint64_t V1Size, const Value *V2,
+                    uint64_t V2Size) {
     return alias(MemoryLocation(V1, V1Size), MemoryLocation(V2, V2Size));
   }
 
-  /// alias - A convenience wrapper.
+  /// A convenience wrapper around the primary \c alias interface.
   AliasResult alias(const Value *V1, const Value *V2) {
     return alias(V1, MemoryLocation::UnknownSize, V2,
                  MemoryLocation::UnknownSize);
   }
 
-  /// isNoAlias - A trivial helper function to check to see if the specified
-  /// pointers are no-alias.
+  /// A trivial helper function to check to see if the specified pointers are
+  /// no-alias.
   bool isNoAlias(const MemoryLocation &LocA, const MemoryLocation &LocB) {
     return alias(LocA, LocB) == NoAlias;
   }
 
-  /// isNoAlias - A convenience wrapper.
-  bool isNoAlias(const Value *V1, uint64_t V1Size,
-                 const Value *V2, uint64_t V2Size) {
+  /// A convenience wrapper around the \c isNoAlias helper interface.
+  bool isNoAlias(const Value *V1, uint64_t V1Size, const Value *V2,
+                 uint64_t V2Size) {
     return isNoAlias(MemoryLocation(V1, V1Size), MemoryLocation(V2, V2Size));
   }
-  
-  /// isNoAlias - A convenience wrapper.
+
+  /// A convenience wrapper around the \c isNoAlias helper interface.
   bool isNoAlias(const Value *V1, const Value *V2) {
     return isNoAlias(MemoryLocation(V1), MemoryLocation(V2));
   }
-  
-  /// isMustAlias - A convenience wrapper.
+
+  /// A trivial helper function to check to see if the specified pointers are
+  /// must-alias.
   bool isMustAlias(const MemoryLocation &LocA, const MemoryLocation &LocB) {
     return alias(LocA, LocB) == MustAlias;
   }
 
-  /// isMustAlias - A convenience wrapper.
+  /// A convenience wrapper around the \c isMustAlias helper interface.
   bool isMustAlias(const Value *V1, const Value *V2) {
     return alias(V1, 1, V2, 1) == MustAlias;
   }
-  
-  /// pointsToConstantMemory - If the specified memory location is
-  /// known to be constant, return true. If OrLocal is true and the
-  /// specified memory location is known to be "local" (derived from
-  /// an alloca), return true. Otherwise return false.
+
+  /// Checks whether the given location points to constant memory, or if
+  /// \p OrLocal is true whether it points to a local alloca.
   virtual bool pointsToConstantMemory(const MemoryLocation &Loc,
                                       bool OrLocal = false);
 
-  /// pointsToConstantMemory - A convenient wrapper.
+  /// A convenience wrapper around the primary \c pointsToConstantMemory
+  /// interface.
   bool pointsToConstantMemory(const Value *P, bool OrLocal = false) {
     return pointsToConstantMemory(MemoryLocation(P), OrLocal);
   }
 
+  /// @}
   //===--------------------------------------------------------------------===//
-  /// Simple mod/ref information...
-  ///
+  /// \name Simple mod/ref information
+  /// @{
 
   /// Get the ModRef info associated with a pointer argument of a callsite. The
   /// result's bits are set to indicate the allowed aliasing ModRef kinds. Note
@@ -263,123 +264,88 @@ public:
   /// information.
   virtual ModRefInfo getArgModRefInfo(ImmutableCallSite CS, unsigned ArgIdx);
 
-  /// getModRefBehavior - Return the behavior when calling the given call site.
+  /// Return the behavior of the given call site.
   virtual FunctionModRefBehavior getModRefBehavior(ImmutableCallSite CS);
 
-  /// getModRefBehavior - Return the behavior when calling the given function.
-  /// For use when the call site is not known.
+  /// Return the behavior when calling the given function.
   virtual FunctionModRefBehavior getModRefBehavior(const Function *F);
 
-  /// doesNotAccessMemory - If the specified call is known to never read or
-  /// write memory, return true.  If the call only reads from known-constant
-  /// memory, it is also legal to return true.  Calls that unwind the stack
-  /// are legal for this predicate.
+  /// Checks if the specified call is known to never read or write memory.
+  ///
+  /// Note that if the call only reads from known-constant memory, it is also
+  /// legal to return true. Also, calls that unwind the stack are legal for
+  /// this predicate.
   ///
   /// Many optimizations (such as CSE and LICM) can be performed on such calls
   /// without worrying about aliasing properties, and many calls have this
   /// property (e.g. calls to 'sin' and 'cos').
   ///
   /// This property corresponds to the GCC 'const' attribute.
-  ///
   bool doesNotAccessMemory(ImmutableCallSite CS) {
     return getModRefBehavior(CS) == FMRB_DoesNotAccessMemory;
   }
 
-  /// doesNotAccessMemory - If the specified function is known to never read or
-  /// write memory, return true.  For use when the call site is not known.
+  /// Checks if the specified function is known to never read or write memory.
   ///
+  /// Note that if the function only reads from known-constant memory, it is
+  /// also legal to return true. Also, function that unwind the stack are legal
+  /// for this predicate.
+  ///
+  /// Many optimizations (such as CSE and LICM) can be performed on such calls
+  /// to such functions without worrying about aliasing properties, and many
+  /// functions have this property (e.g. 'sin' and 'cos').
+  ///
+  /// This property corresponds to the GCC 'const' attribute.
   bool doesNotAccessMemory(const Function *F) {
     return getModRefBehavior(F) == FMRB_DoesNotAccessMemory;
   }
 
-  /// onlyReadsMemory - If the specified call is known to only read from
-  /// non-volatile memory (or not access memory at all), return true.  Calls
-  /// that unwind the stack are legal for this predicate.
+  /// Checks if the specified call is known to only read from non-volatile
+  /// memory (or not access memory at all).
+  ///
+  /// Calls that unwind the stack are legal for this predicate.
   ///
   /// This property allows many common optimizations to be performed in the
   /// absence of interfering store instructions, such as CSE of strlen calls.
   ///
   /// This property corresponds to the GCC 'pure' attribute.
-  ///
   bool onlyReadsMemory(ImmutableCallSite CS) {
     return onlyReadsMemory(getModRefBehavior(CS));
   }
 
-  /// onlyReadsMemory - If the specified function is known to only read from
-  /// non-volatile memory (or not access memory at all), return true.  For use
-  /// when the call site is not known.
+  /// Checks if the specified function is known to only read from non-volatile
+  /// memory (or not access memory at all).
   ///
+  /// Functions that unwind the stack are legal for this predicate.
+  ///
+  /// This property allows many common optimizations to be performed in the
+  /// absence of interfering store instructions, such as CSE of strlen calls.
+  ///
+  /// This property corresponds to the GCC 'pure' attribute.
   bool onlyReadsMemory(const Function *F) {
     return onlyReadsMemory(getModRefBehavior(F));
   }
 
-  /// onlyReadsMemory - Return true if functions with the specified behavior are
-  /// known to only read from non-volatile memory (or not access memory at all).
-  ///
+  /// Checks if functions with the specified behavior are known to only read
+  /// from non-volatile memory (or not access memory at all).
   static bool onlyReadsMemory(FunctionModRefBehavior MRB) {
     return !(MRB & MRI_Mod);
   }
 
-  /// onlyAccessesArgPointees - Return true if functions with the specified
-  /// behavior are known to read and write at most from objects pointed to by
-  /// their pointer-typed arguments (with arbitrary offsets).
-  ///
+  /// Checks if functions with the specified behavior are known to read and
+  /// write at most from objects pointed to by their pointer-typed arguments
+  /// (with arbitrary offsets).
   static bool onlyAccessesArgPointees(FunctionModRefBehavior MRB) {
     return !(MRB & FMRL_Anywhere & ~FMRL_ArgumentPointees);
   }
 
-  /// doesAccessArgPointees - Return true if functions with the specified
-  /// behavior are known to potentially read or write from objects pointed
-  /// to be their pointer-typed arguments (with arbitrary offsets).
-  ///
+  /// Checks if functions with the specified behavior are known to potentially
+  /// read or write from objects pointed to be their pointer-typed arguments
+  /// (with arbitrary offsets).
   static bool doesAccessArgPointees(FunctionModRefBehavior MRB) {
     return (MRB & MRI_ModRef) && (MRB & FMRL_ArgumentPointees);
   }
 
-  /// getModRefInfo - Return information about whether or not an
-  /// instruction may read or write memory (without regard to a
-  /// specific location)
-  ModRefInfo getModRefInfo(const Instruction *I) {
-    if (auto CS = ImmutableCallSite(I)) {
-      auto MRB = getModRefBehavior(CS);
-      if (MRB & MRI_ModRef)
-        return MRI_ModRef;
-      else if (MRB & MRI_Ref)
-        return MRI_Ref;
-      else if (MRB & MRI_Mod)
-        return MRI_Mod;
-      return MRI_NoModRef;
-    }
-
-    return getModRefInfo(I, MemoryLocation());
-  }
-
-  /// getModRefInfo - Return information about whether or not an instruction may
-  /// read or write the specified memory location.  An instruction
-  /// that doesn't read or write memory may be trivially LICM'd for example.
-  ModRefInfo getModRefInfo(const Instruction *I, const MemoryLocation &Loc) {
-    switch (I->getOpcode()) {
-    case Instruction::VAArg:  return getModRefInfo((const VAArgInst*)I, Loc);
-    case Instruction::Load:   return getModRefInfo((const LoadInst*)I,  Loc);
-    case Instruction::Store:  return getModRefInfo((const StoreInst*)I, Loc);
-    case Instruction::Fence:  return getModRefInfo((const FenceInst*)I, Loc);
-    case Instruction::AtomicCmpXchg:
-      return getModRefInfo((const AtomicCmpXchgInst*)I, Loc);
-    case Instruction::AtomicRMW:
-      return getModRefInfo((const AtomicRMWInst*)I, Loc);
-    case Instruction::Call:   return getModRefInfo((const CallInst*)I,  Loc);
-    case Instruction::Invoke: return getModRefInfo((const InvokeInst*)I,Loc);
-    default:
-      return MRI_NoModRef;
-    }
-  }
-
-  /// getModRefInfo - A convenience wrapper.
-  ModRefInfo getModRefInfo(const Instruction *I, const Value *P,
-                           uint64_t Size) {
-    return getModRefInfo(I, MemoryLocation(P, Size));
-  }
-
   /// getModRefInfo (for call sites) - Return information about whether
   /// a particular call site modifies or reads the specified memory location.
   virtual ModRefInfo getModRefInfo(ImmutableCallSite CS,
@@ -473,52 +439,105 @@ public:
   ModRefInfo getModRefInfo(const VAArgInst *I, const Value *P, uint64_t Size) {
     return getModRefInfo(I, MemoryLocation(P, Size));
   }
-  /// getModRefInfo - Return information about whether a call and an instruction
-  /// may refer to the same memory locations.
+
+  /// Check whether or not an instruction may read or write memory (without
+  /// regard to a specific location).
+  ///
+  /// For function calls, this delegates to the alias-analysis specific
+  /// call-site mod-ref behavior queries. Otherwise it delegates to the generic
+  /// mod ref information query without a location.
+  ModRefInfo getModRefInfo(const Instruction *I) {
+    if (auto CS = ImmutableCallSite(I)) {
+      auto MRB = getModRefBehavior(CS);
+      if (MRB & MRI_ModRef)
+        return MRI_ModRef;
+      else if (MRB & MRI_Ref)
+        return MRI_Ref;
+      else if (MRB & MRI_Mod)
+        return MRI_Mod;
+      return MRI_NoModRef;
+    }
+
+    return getModRefInfo(I, MemoryLocation());
+  }
+
+  /// Check whether or not an instruction may read or write the specified
+  /// memory location.
+  ///
+  /// An instruction that doesn't read or write memory may be trivially LICM'd
+  /// for example.
+  ///
+  /// This primarily delegates to specific helpers above.
+  ModRefInfo getModRefInfo(const Instruction *I, const MemoryLocation &Loc) {
+    switch (I->getOpcode()) {
+    case Instruction::VAArg:  return getModRefInfo((const VAArgInst*)I, Loc);
+    case Instruction::Load:   return getModRefInfo((const LoadInst*)I,  Loc);
+    case Instruction::Store:  return getModRefInfo((const StoreInst*)I, Loc);
+    case Instruction::Fence:  return getModRefInfo((const FenceInst*)I, Loc);
+    case Instruction::AtomicCmpXchg:
+      return getModRefInfo((const AtomicCmpXchgInst*)I, Loc);
+    case Instruction::AtomicRMW:
+      return getModRefInfo((const AtomicRMWInst*)I, Loc);
+    case Instruction::Call:   return getModRefInfo((const CallInst*)I,  Loc);
+    case Instruction::Invoke: return getModRefInfo((const InvokeInst*)I,Loc);
+    default:
+      return MRI_NoModRef;
+    }
+  }
+
+  /// A convenience wrapper for constructing the memory location.
+  ModRefInfo getModRefInfo(const Instruction *I, const Value *P,
+                           uint64_t Size) {
+    return getModRefInfo(I, MemoryLocation(P, Size));
+  }
+
+  /// Return information about whether a call and an instruction may refer to
+  /// the same memory locations.
   ModRefInfo getModRefInfo(Instruction *I, ImmutableCallSite Call);
 
-  /// getModRefInfo - Return information about whether two call sites may refer
-  /// to the same set of memory locations.  See 
+  /// Return information about whether two call sites may refer to the same set
+  /// of memory locations. See the AA documentation for details:
   ///   http://llvm.org/docs/AliasAnalysis.html#ModRefInfo
-  /// for details.
   virtual ModRefInfo getModRefInfo(ImmutableCallSite CS1,
                                    ImmutableCallSite CS2);
 
-  /// callCapturesBefore - Return information about whether a particular call 
-  /// site modifies or reads the specified memory location.
+  /// Return information about whether a particular call site modifies or reads
+  /// the specified memory location.
   ModRefInfo callCapturesBefore(const Instruction *I,
                                 const MemoryLocation &MemLoc,
                                 DominatorTree *DT);
 
-  /// callCapturesBefore - A convenience wrapper.
+  /// A convenience wrapper to synthesize a memory location.
   ModRefInfo callCapturesBefore(const Instruction *I, const Value *P,
                                 uint64_t Size, DominatorTree *DT) {
     return callCapturesBefore(I, MemoryLocation(P, Size), DT);
   }
 
+  /// @}
   //===--------------------------------------------------------------------===//
-  /// Higher level methods for querying mod/ref information.
-  ///
+  /// \name Higher level methods for querying mod/ref information.
+  /// @{
 
-  /// canBasicBlockModify - Return true if it is possible for execution of the
-  /// specified basic block to modify the location Loc.
+  /// Check if it is possible for execution of the specified basic block to
+  /// modify the location Loc.
   bool canBasicBlockModify(const BasicBlock &BB, const MemoryLocation &Loc);
 
-  /// canBasicBlockModify - A convenience wrapper.
-  bool canBasicBlockModify(const BasicBlock &BB, const Value *P, uint64_t Size){
+  /// A convenience wrapper synthesizing a memory location.
+  bool canBasicBlockModify(const BasicBlock &BB, const Value *P,
+                           uint64_t Size) {
     return canBasicBlockModify(BB, MemoryLocation(P, Size));
   }
 
-  /// canInstructionRangeModRef - Return true if it is possible for the
-  /// execution of the specified instructions to mod\ref (according to the
-  /// mode) the location Loc. The instructions to consider are all
-  /// of the instructions in the range of [I1,I2] INCLUSIVE.
-  /// I1 and I2 must be in the same basic block.
+  /// Check if it is possible for the execution of the specified instructions
+  /// to mod\ref (according to the mode) the location Loc.
+  ///
+  /// The instructions to consider are all of the instructions in the range of
+  /// [I1,I2] INCLUSIVE. I1 and I2 must be in the same basic block.
   bool canInstructionRangeModRef(const Instruction &I1, const Instruction &I2,
                                  const MemoryLocation &Loc,
                                  const ModRefInfo Mode);
 
-  /// canInstructionRangeModRef - A convenience wrapper.
+  /// A convenience wrapper synthesizing a memory location.
   bool canInstructionRangeModRef(const Instruction &I1, const Instruction &I2,
                                  const Value *Ptr, uint64_t Size,
                                  const ModRefInfo Mode) {