contrib/llvm-project/llvm/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
  24   /// getDefaultMaxUsesToExploreForCaptureTracking - Return default value of
  25   /// the maximal number of uses to explore before giving up. It is used by
  26   /// PointerMayBeCaptured family analysis.
  27   unsigned getDefaultMaxUsesToExploreForCaptureTracking();
  28
  29   /// PointerMayBeCaptured - Return true if this pointer value may be captured
  30   /// by the enclosing function (which is required to exist).  This routine can
  31   /// be expensive, so consider caching the results.  The boolean ReturnCaptures
  32   /// specifies whether returning the value (or part of it) from the function
  33   /// counts as capturing it or not.  The boolean StoreCaptures specified
  34   /// whether storing the value (or part of it) into memory anywhere
  35   /// automatically counts as capturing it or not.
  36   /// MaxUsesToExplore specifies how many uses the analysis should explore for
  37   /// one value before giving up due too "too many uses". If MaxUsesToExplore
  38   /// is zero, a default value is assumed.
  39   bool PointerMayBeCaptured(const Value *V, bool ReturnCaptures,
  40                             bool StoreCaptures,
  41                             unsigned MaxUsesToExplore = 0);
  42
  43   /// PointerMayBeCapturedBefore - Return true if this pointer value may be
  44   /// captured by the enclosing function (which is required to exist). If a
  45   /// DominatorTree is provided, only captures which happen before the given
  46   /// instruction are considered. This routine can be expensive, so consider
  47   /// caching the results.  The boolean ReturnCaptures specifies whether
  48   /// returning the value (or part of it) from the function counts as capturing
  49   /// it or not.  The boolean StoreCaptures specified whether storing the value
  50   /// (or part of it) into memory anywhere automatically counts as capturing it
  51   /// or not. Captures by the provided instruction are considered if the
  52   /// final parameter is true.
  53   /// MaxUsesToExplore specifies how many uses the analysis should explore for
  54   /// one value before giving up due too "too many uses". If MaxUsesToExplore
  55   /// is zero, a default value is assumed.
  56   bool PointerMayBeCapturedBefore(
  57       const Value *V, bool ReturnCaptures, bool StoreCaptures,
  58       const Instruction *I, const DominatorTree *DT, bool IncludeI = false,
  59       unsigned MaxUsesToExplore = 0);
  60
  61   /// This callback is used in conjunction with PointerMayBeCaptured. In
  62   /// addition to the interface here, you'll need to provide your own getters
  63   /// to see whether anything was captured.
  64   struct CaptureTracker {
  65     virtual ~CaptureTracker();
  66
  67     /// tooManyUses - The depth of traversal has breached a limit. There may be
  68     /// capturing instructions that will not be passed into captured().
  69     virtual void tooManyUses() = 0;
  70
  71     /// shouldExplore - This is the use of a value derived from the pointer.
  72     /// To prune the search (ie., assume that none of its users could possibly
  73     /// capture) return false. To search it, return true.
  74     ///
  75     /// U->getUser() is always an Instruction.
  76     virtual bool shouldExplore(const Use *U);
  77
  78     /// captured - Information about the pointer was captured by the user of
  79     /// use U. Return true to stop the traversal or false to continue looking
  80     /// for more capturing instructions.
  81     virtual bool captured(const Use *U) = 0;
  82
  83     /// isDereferenceableOrNull - Overload to allow clients with additional
  84     /// knowledge about pointer dereferenceability to provide it and thereby
  85     /// avoid conservative responses when a pointer is compared to null.
  86     virtual bool isDereferenceableOrNull(Value *O, const DataLayout &DL);
  87   };
  88
  89   /// PointerMayBeCaptured - Visit the value and the values derived from it and
  90   /// find values which appear to be capturing the pointer value. This feeds
  91   /// results into and is controlled by the CaptureTracker object.
  92   /// MaxUsesToExplore specifies how many uses the analysis should explore for
  93   /// one value before giving up due too "too many uses". If MaxUsesToExplore
  94   /// is zero, a default value is assumed.
  95   void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker,
  96                             unsigned MaxUsesToExplore = 0);
  97 } // end namespace llvm
  98
  99 #endif