• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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.
36   DoNothing,
37 
38   /// The argument is treated as if an -autorelease message had been sent to
39   /// the referenced object.
40   Autorelease,
41 
42   /// The argument is treated as if an -dealloc message had been sent to
43   /// the referenced object.
44   Dealloc,
45 
46   /// The argument has its reference count decreased by 1.  This is as
47   /// if CFRelease has been called on the argument.
48   DecRef,
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.
53   DecRefMsg,
54 
55   /// The argument has its reference count decreased by 1 to model
56   /// a transferred bridge cast under ARC.
57   DecRefBridgedTransferred,
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.
62   IncRefMsg,
63 
64   /// The argument has its reference count increased by 1.  This is as
65   /// if CFRetain has been called on the argument.
66   IncRef,
67 
68   /// The argument acts as if has been passed to CFMakeCollectable, which
69   /// transfers the object to the Garbage Collector under GC.
70   MakeCollectable,
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.
74   UnretainedOutParameter,
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.
78   RetainedOutParameter,
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.
83   MayEscape,
84 
85   /// All typestate tracking of the object ceases.  This is usually employed
86   /// when the effect of the call is completely unknown.
87   StopTracking,
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.
96   StopTrackingHard,
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.
103   DecRefAndStopTrackingHard,
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.
110   DecRefMsgAndStopTrackingHard
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.
120     NoRet,
121     /// Indicates that the returned value is an owned (+1) symbol.
122     OwnedSymbol,
123     /// Indicates that the returned value is an owned (+1) symbol and
124     /// that it should be treated as freshly allocated.
125     OwnedAllocatedSymbol,
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.
129     NotOwnedSymbol,
130     /// Indicates that the object is not owned and controlled by the
131     /// Garbage collector.
132     GCNotOwnedSymbol,
133     /// Indicates that the return value is an owned object when the
134     /// receiver is also a tracked object.
135     OwnedWhenTrackedReceiver,
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
140     NoRetHard
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.
149     ObjC,
150     /// Indicates that the tracked object could be a CF or Objective-C object.
151     AnyObj
152   };
153 
154 private:
155   Kind K;
156   ObjKind O;
157 
K(k)158   RetEffect(Kind k, ObjKind o = AnyObj) : K(k), O(o) {}
159 
160 public:
getKind()161   Kind getKind() const { return K; }
162 
getObjKind()163   ObjKind getObjKind() const { return O; }
164 
isOwned()165   bool isOwned() const {
166     return K == OwnedSymbol || K == OwnedAllocatedSymbol ||
167     K == OwnedWhenTrackedReceiver;
168   }
169 
notOwned()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 
MakeOwnedWhenTrackedReceiver()178   static RetEffect MakeOwnedWhenTrackedReceiver() {
179     return RetEffect(OwnedWhenTrackedReceiver, ObjC);
180   }
181 
182   static RetEffect MakeOwned(ObjKind o, bool isAllocated = false) {
183     return RetEffect(isAllocated ? OwnedAllocatedSymbol : OwnedSymbol, o);
184   }
MakeNotOwned(ObjKind o)185   static RetEffect MakeNotOwned(ObjKind o) {
186     return RetEffect(NotOwnedSymbol, o);
187   }
MakeGCNotOwned()188   static RetEffect MakeGCNotOwned() {
189     return RetEffect(GCNotOwnedSymbol, ObjC);
190   }
MakeNoRet()191   static RetEffect MakeNoRet() {
192     return RetEffect(NoRet);
193   }
MakeNoRetHard()194   static RetEffect MakeNoRetHard() {
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 {
208   llvm::SmallVector<ArgEffect, 10> Args;
209   RetEffect Ret;
210   ArgEffect Receiver;
211 
CallEffects(const RetEffect & R)212   CallEffects(const RetEffect &R) : Ret(R) {}
213 
214 public:
215   /// Returns the argument effects for a call.
getArgs()216   ArrayRef<ArgEffect> getArgs() const { return Args; }
217 
218   /// Returns the effects on the receiver.
getReceiver()219   ArgEffect getReceiver() const { return Receiver; }
220 
221   /// Returns the effect on the return value.
getReturnValue()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 
235