]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - contrib/llvm/include/llvm/Analysis/CaptureTracking.h
blacklist: update to NetBSD snapshot on 20191106
[FreeBSD/FreeBSD.git] / contrib / 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 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