LLVM  10.0.0svn
CaptureTracking.h
Go to the documentation of this file.
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 Instruction;
21  class DominatorTree;
22  class OrderedBasicBlock;
23 
24  /// The default value for MaxUsesToExplore argument. It's relatively small to
25  /// keep the cost of analysis reasonable for clients like BasicAliasAnalysis,
26  /// where the results can't be cached.
27  /// TODO: we should probably introduce a caching CaptureTracking analysis and
28  /// use it where possible. The caching version can use much higher limit or
29  /// don't have this cap at all.
30  unsigned constexpr DefaultMaxUsesToExplore = 20;
31 
32  /// PointerMayBeCaptured - Return true if this pointer value may be captured
33  /// by the enclosing function (which is required to exist). This routine can
34  /// be expensive, so consider caching the results. The boolean ReturnCaptures
35  /// specifies whether returning the value (or part of it) from the function
36  /// counts as capturing it or not. The boolean StoreCaptures specified
37  /// whether storing the value (or part of it) into memory anywhere
38  /// automatically counts as capturing it or not.
39  /// MaxUsesToExplore specifies how many uses should the analysis explore for
40  /// one value before giving up due too "too many uses".
41  bool PointerMayBeCaptured(const Value *V,
42  bool ReturnCaptures,
43  bool StoreCaptures,
44  unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
45 
46  /// PointerMayBeCapturedBefore - Return true if this pointer value may be
47  /// captured by the enclosing function (which is required to exist). If a
48  /// DominatorTree is provided, only captures which happen before the given
49  /// instruction are considered. This routine can be expensive, so consider
50  /// caching the results. The boolean ReturnCaptures specifies whether
51  /// returning the value (or part of it) from the function counts as capturing
52  /// it or not. The boolean StoreCaptures specified whether storing the value
53  /// (or part of it) into memory anywhere automatically counts as capturing it
54  /// or not. Captures by the provided instruction are considered if the
55  /// final parameter is true. An ordered basic block in \p OBB could be used
56  /// to speed up capture-tracker queries.
57  /// MaxUsesToExplore specifies how many uses should the analysis explore for
58  /// one value before giving up due too "too many uses".
59  bool PointerMayBeCapturedBefore(const Value *V, bool ReturnCaptures,
60  bool StoreCaptures, const Instruction *I,
61  const DominatorTree *DT, bool IncludeI = false,
62  OrderedBasicBlock *OBB = nullptr,
63  unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
64 
65  /// This callback is used in conjunction with PointerMayBeCaptured. In
66  /// addition to the interface here, you'll need to provide your own getters
67  /// to see whether anything was captured.
68  struct CaptureTracker {
69  virtual ~CaptureTracker();
70 
71  /// tooManyUses - The depth of traversal has breached a limit. There may be
72  /// capturing instructions that will not be passed into captured().
73  virtual void tooManyUses() = 0;
74 
75  /// shouldExplore - This is the use of a value derived from the pointer.
76  /// To prune the search (ie., assume that none of its users could possibly
77  /// capture) return false. To search it, return true.
78  ///
79  /// U->getUser() is always an Instruction.
80  virtual bool shouldExplore(const Use *U);
81 
82  /// captured - Information about the pointer was captured by the user of
83  /// use U. Return true to stop the traversal or false to continue looking
84  /// for more capturing instructions.
85  virtual bool captured(const Use *U) = 0;
86  };
87 
88  /// PointerMayBeCaptured - Visit the value and the values derived from it and
89  /// find values which appear to be capturing the pointer value. This feeds
90  /// results into and is controlled by the CaptureTracker object.
91  /// MaxUsesToExplore specifies how many uses should the analysis explore for
92  /// one value before giving up due too "too many uses".
93  void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker,
94  unsigned MaxUsesToExplore = DefaultMaxUsesToExplore);
95 } // end namespace llvm
96 
97 #endif
virtual void tooManyUses()=0
tooManyUses - The depth of traversal has breached a limit.
This callback is used in conjunction with PointerMayBeCaptured.
This class represents lattice values for constants.
Definition: AllocatorList.h:23
unsigned constexpr DefaultMaxUsesToExplore
The default value for MaxUsesToExplore argument.
virtual bool shouldExplore(const Use *U)
shouldExplore - This is the use of a value derived from the pointer.
A Use represents the edge between a Value definition and its users.
Definition: Use.h:55
virtual bool captured(const Use *U)=0
captured - Information about the pointer was captured by the user of use U.
bool PointerMayBeCapturedBefore(const Value *V, bool ReturnCaptures, bool StoreCaptures, const Instruction *I, const DominatorTree *DT, bool IncludeI=false, OrderedBasicBlock *OBB=nullptr, unsigned MaxUsesToExplore=DefaultMaxUsesToExplore)
PointerMayBeCapturedBefore - Return true if this pointer value may be captured by the enclosing funct...
Concrete subclass of DominatorTreeBase that is used to compute a normal dominator tree...
Definition: Dominators.h:144
#define I(x, y, z)
Definition: MD5.cpp:58
LLVM Value Representation.
Definition: Value.h:73
bool PointerMayBeCaptured(const Value *V, bool ReturnCaptures, bool StoreCaptures, unsigned MaxUsesToExplore=DefaultMaxUsesToExplore)
PointerMayBeCaptured - Return true if this pointer value may be captured by the enclosing function (w...