[llvm] 71d1059 - [CaptureTracking][NFC] Clarify usage expectations in PointerMayBeCaptured comments (#132744)

[via llvm-commits]

Author: Camsyn
Date: 2025-04-14T18:06:33+02:00
New Revision: 71d10590dbc041139644f00144513c7f487a94ba

URL: https://github.com/llvm/llvm-project/commit/71d10590dbc041139644f00144513c7f487a94ba
DIFF: https://github.com/llvm/llvm-project/commit/71d10590dbc041139644f00144513c7f487a94ba.diff

LOG: [CaptureTracking][NFC] Clarify usage expectations in PointerMayBeCaptured comments (#132744)

Fixes issue #132739.

CaptureAnalysis only considers captures through the def-use chain of the
provided pointer, explicitly excluding captures of underlying values or
implicit captures like those involving external globals.

The previous comment for `PointerMayBeCaptured` did not clearly state
this limitation, leading to its incorrect usage in files such as
ThreadSanitizer.cpp and SanitizerMetadata.cpp.

This PR addresses this by refining the comments for the relevant APIs
within `PointerMayBeCaptured` to explicitly document this behavior.

Added: 
    

Modified: 
    llvm/include/llvm/Analysis/CaptureTracking.h

Removed: 
    


################################################################################
diff  --git a/llvm/include/llvm/Analysis/CaptureTracking.h b/llvm/include/llvm/Analysis/CaptureTracking.h
index 8c54851571cff..bd8d2bb568876 100644
--- a/llvm/include/llvm/Analysis/CaptureTracking.h
+++ b/llvm/include/llvm/Analysis/CaptureTracking.h
@@ -41,6 +41,9 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   bool PointerMayBeCaptured(const Value *V, bool ReturnCaptures,
                             unsigned MaxUsesToExplore = 0);
 
@@ -48,6 +51,9 @@ namespace llvm {
   /// components that are part of \p Mask. Once \p StopFn on the accumulated
   /// components returns true, the traversal is aborted early. By default, this
   /// happens when *any* of the components in \p Mask are captured.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   CaptureComponents PointerMayBeCaptured(
       const Value *V, bool ReturnCaptures, CaptureComponents Mask,
       function_ref<bool(CaptureComponents)> StopFn = capturesAnything,
@@ -64,6 +70,9 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   bool PointerMayBeCapturedBefore(const Value *V, bool ReturnCaptures,
                                   const Instruction *I, const DominatorTree *DT,
                                   bool IncludeI = false,
@@ -75,6 +84,9 @@ namespace llvm {
   /// on the accumulated components returns true, the traversal is aborted
   /// early. By default, this happens when *any* of the components in \p Mask
   /// are captured.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   CaptureComponents PointerMayBeCapturedBefore(
       const Value *V, bool ReturnCaptures, const Instruction *I,
       const DominatorTree *DT, bool IncludeI, CaptureComponents Mask,
@@ -184,6 +196,9 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker,
                             unsigned MaxUsesToExplore = 0);