1//===----- llvm/Analysis/CaptureTracking.h - Pointer capture ----*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file contains routines that help determine which pointers are captured.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_ANALYSIS_CAPTURETRACKING_H
15#define LLVM_ANALYSIS_CAPTURETRACKING_H
16
17namespace llvm {
18
19  class Value;
20  class Use;
21
22  /// PointerMayBeCaptured - Return true if this pointer value may be captured
23  /// by the enclosing function (which is required to exist).  This routine can
24  /// be expensive, so consider caching the results.  The boolean ReturnCaptures
25  /// specifies whether returning the value (or part of it) from the function
26  /// counts as capturing it or not.  The boolean StoreCaptures specified
27  /// whether storing the value (or part of it) into memory anywhere
28  /// automatically counts as capturing it or not.
29  bool PointerMayBeCaptured(const Value *V,
30                            bool ReturnCaptures,
31                            bool StoreCaptures);
32
33  /// This callback is used in conjunction with PointerMayBeCaptured. In
34  /// addition to the interface here, you'll need to provide your own getters
35  /// to see whether anything was captured.
36  struct CaptureTracker {
37    virtual ~CaptureTracker();
38
39    /// tooManyUses - The depth of traversal has breached a limit. There may be
40    /// capturing instructions that will not be passed into captured().
41    virtual void tooManyUses() = 0;
42
43    /// shouldExplore - This is the use of a value derived from the pointer.
44    /// To prune the search (ie., assume that none of its users could possibly
45    /// capture) return false. To search it, return true.
46    ///
47    /// U->getUser() is always an Instruction.
48    virtual bool shouldExplore(const Use *U);
49
50    /// captured - Information about the pointer was captured by the user of
51    /// use U. Return true to stop the traversal or false to continue looking
52    /// for more capturing instructions.
53    virtual bool captured(const Use *U) = 0;
54  };
55
56  /// PointerMayBeCaptured - Visit the value and the values derived from it and
57  /// find values which appear to be capturing the pointer value. This feeds
58  /// results into and is controlled by the CaptureTracker object.
59  void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker);
60} // end namespace llvm
61
62#endif
63