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
16namespace 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
100