clang  3.9.0
ObjCRetainCount.h
Go to the documentation of this file.
1 //==-- ObjCRetainCount.h - Retain count summaries for Cocoa -------*- 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 defines the core data structures for retain count "summaries"
11 // for Objective-C and Core Foundation APIs. These summaries are used
12 // by the static analyzer to summarize the retain/release effects of
13 // function and method calls. This drives a path-sensitive typestate
14 // analysis in the static analyzer, but can also potentially be used by
15 // other clients.
16 //
17 //===----------------------------------------------------------------------===//
18 
19 #ifndef LLVM_CLANG_STATICANALYZER_CHECKERS_OBJCRETAINCOUNT_H
20 #define LLVM_CLANG_STATICANALYZER_CHECKERS_OBJCRETAINCOUNT_H
21 
22 #include "clang/Basic/LLVM.h"
23 #include "llvm/ADT/ArrayRef.h"
24 #include "llvm/ADT/SmallVector.h"
25 
26 namespace clang {
27 class FunctionDecl;
28 class ObjCMethodDecl;
29 
30 namespace ento { namespace objc_retain {
31 
32 /// An ArgEffect summarizes the retain count behavior on an argument or receiver
33 /// to a function or method.
34 enum ArgEffect {
35  /// There is no effect.
37 
38  /// The argument is treated as if an -autorelease message had been sent to
39  /// the referenced object.
41 
42  /// The argument is treated as if an -dealloc message had been sent to
43  /// the referenced object.
45 
46  /// The argument has its reference count decreased by 1. This is as
47  /// if CFRelease has been called on the argument.
49 
50  /// The argument has its reference count decreased by 1. This is as
51  /// if a -release message has been sent to the argument. This differs
52  /// in behavior from DecRef when GC is enabled.
54 
55  /// The argument has its reference count decreased by 1 to model
56  /// a transferred bridge cast under ARC.
58 
59  /// The argument has its reference count increased by 1. This is as
60  /// if a -retain message has been sent to the argument. This differs
61  /// in behavior from IncRef when GC is enabled.
63 
64  /// The argument has its reference count increased by 1. This is as
65  /// if CFRetain has been called on the argument.
67 
68  /// The argument acts as if has been passed to CFMakeCollectable, which
69  /// transfers the object to the Garbage Collector under GC.
71 
72  /// The argument is a pointer to a retain-counted object; on exit, the new
73  /// value of the pointer is a +0 value or NULL.
75 
76  /// The argument is a pointer to a retain-counted object; on exit, the new
77  /// value of the pointer is a +1 value or NULL.
79 
80  /// The argument is treated as potentially escaping, meaning that
81  /// even when its reference count hits 0 it should be treated as still
82  /// possibly being alive as someone else *may* be holding onto the object.
84 
85  /// All typestate tracking of the object ceases. This is usually employed
86  /// when the effect of the call is completely unknown.
88 
89  /// All typestate tracking of the object ceases. Unlike StopTracking,
90  /// this is also enforced when the method body is inlined.
91  ///
92  /// In some cases, we obtain a better summary for this checker
93  /// by looking at the call site than by inlining the function.
94  /// Signifies that we should stop tracking the symbol even if
95  /// the function is inlined.
97 
98  /// Performs the combined functionality of DecRef and StopTrackingHard.
99  ///
100  /// The models the effect that the called function decrements the reference
101  /// count of the argument and all typestate tracking on that argument
102  /// should cease.
104 
105  /// Performs the combined functionality of DecRefMsg and StopTrackingHard.
106  ///
107  /// The models the effect that the called function decrements the reference
108  /// count of the argument and all typestate tracking on that argument
109  /// should cease.
111 };
112 
113 /// RetEffect summarizes a call's retain/release behavior with respect
114 /// to its return value.
115 class RetEffect {
116 public:
117  enum Kind {
118  /// Indicates that no retain count information is tracked for
119  /// the return value.
121  /// Indicates that the returned value is an owned (+1) symbol.
123  /// Indicates that the returned value is an owned (+1) symbol and
124  /// that it should be treated as freshly allocated.
126  /// Indicates that the returned value is an object with retain count
127  /// semantics but that it is not owned (+0). This is the default
128  /// for getters, etc.
130  /// Indicates that the object is not owned and controlled by the
131  /// Garbage collector.
133  /// Indicates that the return value is an owned object when the
134  /// receiver is also a tracked object.
136  // Treat this function as returning a non-tracked symbol even if
137  // the function has been inlined. This is used where the call
138  // site summary is more presise than the summary indirectly produced
139  // by inlining the function
141  };
142 
143  /// Determines the object kind of a tracked object.
144  enum ObjKind {
145  /// Indicates that the tracked object is a CF object. This is
146  /// important between GC and non-GC code.
147  CF,
148  /// Indicates that the tracked object is an Objective-C object.
150  /// Indicates that the tracked object could be a CF or Objective-C object.
152  };
153 
154 private:
155  Kind K;
156  ObjKind O;
157 
158  RetEffect(Kind k, ObjKind o = AnyObj) : K(k), O(o) {}
159 
160 public:
161  Kind getKind() const { return K; }
162 
163  ObjKind getObjKind() const { return O; }
164 
165  bool isOwned() const {
166  return K == OwnedSymbol || K == OwnedAllocatedSymbol ||
168  }
169 
170  bool notOwned() const {
171  return K == NotOwnedSymbol;
172  }
173 
174  bool operator==(const RetEffect &Other) const {
175  return K == Other.K && O == Other.O;
176  }
177 
180  }
181 
182  static RetEffect MakeOwned(ObjKind o, bool isAllocated = false) {
183  return RetEffect(isAllocated ? OwnedAllocatedSymbol : OwnedSymbol, o);
184  }
186  return RetEffect(NotOwnedSymbol, o);
187  }
190  }
191  static RetEffect MakeNoRet() {
192  return RetEffect(NoRet);
193  }
195  return RetEffect(NoRetHard);
196  }
197 };
198 
199 /// Encapsulates the retain count semantics on the arguments, return value,
200 /// and receiver (if any) of a function/method call.
201 ///
202 /// Note that construction of these objects is not highly efficient. That
203 /// is okay for clients where creating these objects isn't really a bottleneck.
204 /// The purpose of the API is to provide something simple. The actual
205 /// static analyzer checker that implements retain/release typestate
206 /// tracking uses something more efficient.
207 class CallEffects {
209  RetEffect Ret;
210  ArgEffect Receiver;
211 
212  CallEffects(const RetEffect &R) : Ret(R) {}
213 
214 public:
215  /// Returns the argument effects for a call.
216  ArrayRef<ArgEffect> getArgs() const { return Args; }
217 
218  /// Returns the effects on the receiver.
219  ArgEffect getReceiver() const { return Receiver; }
220 
221  /// Returns the effect on the return value.
222  RetEffect getReturnValue() const { return Ret; }
223 
224  /// Return the CallEfect for a given Objective-C method.
225  static CallEffects getEffect(const ObjCMethodDecl *MD);
226 
227  /// Return the CallEfect for a given C/C++ function.
228  static CallEffects getEffect(const FunctionDecl *FD);
229 };
230 
231 }}}
232 
233 #endif
234 
FunctionDecl - An instance of this class is created to represent a function declaration or definition...
Definition: Decl.h:1561
static RetEffect MakeOwnedWhenTrackedReceiver()
The argument acts as if has been passed to CFMakeCollectable, which transfers the object to the Garba...
The argument has its reference count decreased by 1.
Indicates that the tracked object is an Objective-C object.
The argument is a pointer to a retain-counted object; on exit, the new value of the pointer is a +1 v...
ObjCMethodDecl - Represents an instance or class method declaration.
Definition: DeclObjC.h:113
The argument is treated as if an -autorelease message had been sent to the referenced object...
RetEffect getReturnValue() const
Returns the effect on the return value.
The argument has its reference count increased by 1.
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
bool operator==(const RetEffect &Other) const
ArgEffect
An ArgEffect summarizes the retain count behavior on an argument or receiver to a function or method...
Indicates that the returned value is an owned (+1) symbol.
Indicates that the return value is an owned object when the receiver is also a tracked object...
The argument is treated as potentially escaping, meaning that even when its reference count hits 0 it...
ArrayRef< ArgEffect > getArgs() const
Returns the argument effects for a call.
Indicates that the tracked object is a CF object.
Indicates that the object is not owned and controlled by the Garbage collector.
static CallEffects getEffect(const ObjCMethodDecl *MD)
Return the CallEfect for a given Objective-C method.
ObjKind
Determines the object kind of a tracked object.
static RetEffect MakeOwned(ObjKind o, bool isAllocated=false)
static RetEffect MakeNotOwned(ObjKind o)
ArgEffect getReceiver() const
Returns the effects on the receiver.
Kind
The argument has its reference count increased by 1.
The argument has its reference count decreased by 1 to model a transferred bridge cast under ARC...
All typestate tracking of the object ceases.
The argument is treated as if an -dealloc message had been sent to the referenced object...
Performs the combined functionality of DecRef and StopTrackingHard.
RetEffect summarizes a call's retain/release behavior with respect to its return value.
Indicates that the returned value is an owned (+1) symbol and that it should be treated as freshly al...
Performs the combined functionality of DecRefMsg and StopTrackingHard.
The argument is a pointer to a retain-counted object; on exit, the new value of the pointer is a +0 v...
Indicates that no retain count information is tracked for the return value.
All typestate tracking of the object ceases.
The argument has its reference count decreased by 1.
Encapsulates the retain count semantics on the arguments, return value, and receiver (if any) of a fu...
Indicates that the returned value is an object with retain count semantics but that it is not owned (...
Indicates that the tracked object could be a CF or Objective-C object.