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 104