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  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