include/llvm/Analysis/CaptureTracking.h

   1 //===----- llvm/Analysis/CaptureTracking.h - Pointer capture ----*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file contains routines that help determine which pointers are captured.
  10 //
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef LLVM_ANALYSIS_CAPTURETRACKING_H
  14 #define LLVM_ANALYSIS_CAPTURETRACKING_H
  15
  16 namespace llvm {
  17
  18   class Value;
  19   class Use;
  20   class DataLayout;
  21   class Instruction;
  22   class DominatorTree;
  23   class OrderedBasicBlock;
  24
  25   /// The default value for MaxUsesToExplore argument. It's relatively small to
  26   /// keep the cost of analysis reasonable for clients like BasicAliasAnalysis,
  27   /// where the results can't be cached.
  28   /// TODO: we should probably introduce a caching CaptureTracking analysis and
  29   /// use it where possible. The caching version can use much higher limit or
  30   /// don't have this cap at all.
  31   unsigned constexpr DefaultMaxUsesToExplore = 20;
  32
  33   /// PointerMayBeCaptured - Return true if this pointer value may be captured
  34   /// by the enclosing function (which is required to exist).  This routine can
  35   /// be expensive, so consider caching the results.  The boolean ReturnCaptures
  36   /// specifies whether returning the value (or part of it) from the function
  37   /// counts as capturing it or not.  The boolean StoreCaptures specified
  38   /// whether storing the value (or part of it) into memory anywhere
  39   /// automatically counts as capturing it or not.
  40   /// MaxUsesToExplore specifies how many uses should the analysis explore for
  41   /// one value before giving up due too "too many uses".
  42   bool PointerMayBeCaptured(const Value *V,
  43                             bool ReturnCaptures,
  44                             bool StoreCaptures,
  45                             unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
  46
  47   /// PointerMayBeCapturedBefore - Return true if this pointer value may be
  48   /// captured by the enclosing function (which is required to exist). If a
  49   /// DominatorTree is provided, only captures which happen before the given
  50   /// instruction are considered. This routine can be expensive, so consider
  51   /// caching the results.  The boolean ReturnCaptures specifies whether
  52   /// returning the value (or part of it) from the function counts as capturing
  53   /// it or not.  The boolean StoreCaptures specified whether storing the value
  54   /// (or part of it) into memory anywhere automatically counts as capturing it
  55   /// or not. Captures by the provided instruction are considered if the
  56   /// final parameter is true. An ordered basic block in \p OBB could be used
  57   /// to speed up capture-tracker queries.
  58   /// MaxUsesToExplore specifies how many uses should the analysis explore for
  59   /// one value before giving up due too "too many uses".
  60   bool PointerMayBeCapturedBefore(const Value *V, bool ReturnCaptures,
  61                                   bool StoreCaptures, const Instruction *I,
  62                                   const DominatorTree *DT, bool IncludeI = false,
  63                                   OrderedBasicBlock *OBB = nullptr,
  64                                   unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
  65
  66   /// This callback is used in conjunction with PointerMayBeCaptured. In
  67   /// addition to the interface here, you'll need to provide your own getters
  68   /// to see whether anything was captured.
  69   struct CaptureTracker {
  70     virtual ~CaptureTracker();
  71
  72     /// tooManyUses - The depth of traversal has breached a limit. There may be
  73     /// capturing instructions that will not be passed into captured().
  74     virtual void tooManyUses() = 0;
  75
  76     /// shouldExplore - This is the use of a value derived from the pointer.
  77     /// To prune the search (ie., assume that none of its users could possibly
  78     /// capture) return false. To search it, return true.
  79     ///
  80     /// U->getUser() is always an Instruction.
  81     virtual bool shouldExplore(const Use *U);
  82
  83     /// captured - Information about the pointer was captured by the user of
  84     /// use U. Return true to stop the traversal or false to continue looking
  85     /// for more capturing instructions.
  86     virtual bool captured(const Use *U) = 0;
  87
  88     /// isDereferenceableOrNull - Overload to allow clients with additional
  89     /// knowledge about pointer dereferenceability to provide it and thereby
  90     /// avoid conservative responses when a pointer is compared to null.
  91     virtual bool isDereferenceableOrNull(Value *O, const DataLayout &DL);
  92   };
  93
  94   /// PointerMayBeCaptured - Visit the value and the values derived from it and
  95   /// find values which appear to be capturing the pointer value. This feeds
  96   /// results into and is controlled by the CaptureTracker object.
  97   /// MaxUsesToExplore specifies how many uses should the analysis explore for
  98   /// one value before giving up due too "too many uses".
  99   void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker,
 100                             unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
 101 } // end namespace llvm
 102
 103 #endif