00001 /* 00002 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. 00003 * 00004 * Licensed under the Universal Permissive License v 1.0 as shown at 00005 * http://oss.oracle.com/licenses/upl. 00006 */ 00007 #ifndef COH_HEAP_ANALYZER_HPP 00008 #define COH_HEAP_ANALYZER_HPP 00009 00010 #include "coherence/lang/interface_spec.hpp" 00011 #include "coherence/lang/Object.hpp" 00012 #include "coherence/lang/TypedHandle.hpp" 00013 00014 COH_OPEN_NAMESPACE2(coherence,lang) 00015 00016 00017 /** 00018 * HeapAnalyzer provides a base diagnostics interface for tracking heap usage. 00019 * 00020 * There is at most one HeapAnalyzer registered with the system for the 00021 * lifetime of the process. The HeapAnalyzer implementation may be specified 00022 * via the "coherence.heap.analyzer" system property. The property 00023 * can be set to one of the following values: 00024 * <ul> 00025 * <li>none No heap analysis will be performed.</li> 00026 * <li>object The coherence::lang::ObjectCountHeapAnalyzer will be used.</li> 00027 * <li>class The coherence::lang::ClassBasedHeapAnalyzer will be used.</li> 00028 * <li>alloc The coherence::lang::ClassBasedHeapAnalyzer will be used, 00029 * in allocation analysis mode.</li> 00030 * <li>[custom] The name of a class registered with the SystemClassLoader.</li> 00031 * </ul> 00032 * 00033 * In the case where a custom class is specified, it must implement this 00034 * interface. The custom analyzer will be initialized as soon as the class 00035 * is registered with the SystemClassLoader. As static initialization order 00036 * cannot be guaranteed, this custom analyzer will not be notified of managed 00037 * objects created earlier in the static initialization order. 00038 * 00039 * The active analyzer may be obtained from the System::getHeapAnalyzer() 00040 * method. 00041 * 00042 * The HeapAnalyzer and Snapshot interfaces are intentionally narrow. 00043 * Implementations are expected to provide useful information via the toString 00044 * method, as well as by possibly augmenting the interfaces. The minimal 00045 * interface is sufficient for detecting memory leaks. 00046 * 00047 * HeapAnalyzer::Snapshot::View vSnap = hAnalyzer->capture(); 00048 * ... 00049 * ... 00050 * std::cout << "Heap changed by: " << hAnalyzer->delta(vSnap) << std::endl; 00051 * 00052 * @see ObjectCountHeapAnalyzer 00053 * @see ClassBasedHeapAnalyzer 00054 * 00055 * @author mf 2008.04.27 00056 */ 00057 class COH_EXPORT HeapAnalyzer 00058 : public interface_spec<HeapAnalyzer> 00059 { 00060 // ----- nested interface: Snapshot ------------------------------------- 00061 00062 public: 00063 /** 00064 * Snapshot provides a abstract mechanism for comparing successive 00065 * heap analysis points. 00066 */ 00067 class COH_EXPORT Snapshot 00068 : public interface_spec<Snapshot> 00069 { 00070 // ----- Snapshot interface --------------------------------- 00071 00072 public: 00073 /** 00074 * Return the number of registered objects reflected by this 00075 * snapshot. 00076 * 00077 * @return the number of registered objects 00078 */ 00079 virtual int64_t getObjectCount() const = 0; 00080 00081 /** 00082 * Return the result of "subtracting" the supplied Snapshot 00083 * from this Snapshot. 00084 * 00085 * @param vThat the snapshot to compare against 00086 * 00087 * @return the delta between two snapshots 00088 */ 00089 virtual Snapshot::View delta(Snapshot::View vThat) const = 0; 00090 }; 00091 00092 00093 // ----- HeapAnalyzer interface ----------------------------------------- 00094 00095 public: 00096 /** 00097 * Capture a Snapshot of the current state of the heap. 00098 * 00099 * Note, when performing captures in a loop, and assigning the captured 00100 * snapshot to a handle referencing a snapshot, it is advisable to 00101 * NULL out the handle first, so as to avoid the new snapshot including 00102 * the "cost" of snapshot it is about to replace. 00103 * 00104 * @return a Snapshot of the current state of the heap. 00105 */ 00106 virtual Snapshot::View capture() const = 0; 00107 00108 /** 00109 * Compute the delta between the supplied Snapshot and the current heap 00110 * state. 00111 * 00112 * @param vThat the snapshot to compare against. 00113 * 00114 * @return a snapshot containing the delta 00115 */ 00116 virtual Snapshot::View delta(Snapshot::View vThat) const = 0; 00117 00118 /** 00119 * Return the number of registered objects. 00120 * 00121 * @return the number of registered objects 00122 */ 00123 virtual int64_t getObjectCount() const = 0; 00124 00125 /** 00126 * Return the number of objects which have been marked as uncollectable. 00127 * 00128 * Return the number of objects which have been marked as uncollectable. 00129 */ 00130 virtual int64_t getImmortalCount() const = 0; 00131 00132 protected: 00133 /** 00134 * Register a newly created Object with the system. 00135 * 00136 * This method is called automatically by coherence::lang::Object once 00137 * the Object has finished construction. 00138 * 00139 * @param o the newly created Object. 00140 */ 00141 virtual void registerObject(const Object& o) = 0; 00142 00143 /** 00144 * Unregister an Object with the system. 00145 * 00146 * This method is called automatically by coherence::lang::Object 00147 * just prior to the deletion of the Object. No new handles or views 00148 * may be created to the object. 00149 * 00150 * @param o the Object to unregister 00151 */ 00152 virtual void unregisterObject(const Object& o) = 0; 00153 00154 /** 00155 * Invoked when an object is deemed to immortal and can never be collected. 00156 * 00157 * Note the specified object will have already been registered via registerObject. 00158 */ 00159 virtual void registerImmortal(const Object& o) = 0; 00160 00161 00162 // ----- static helper methods ------------------------------------------ 00163 00164 public: 00165 /** 00166 * Ensure that the delta between the current heap and the supplied 00167 * snapshot is as expected. 00168 * 00169 * This method can be used to perform quick memory leak assertions. 00170 * 00171 * @code 00172 * HeapAnalyzer::Snapshot::View vSnapStart = HeapAnalyzer::ensureHeap(); 00173 * ... 00174 * ... 00175 * HeapAnalyzer::ensureHeap(vSnapStart); 00176 * @endcode 00177 * 00178 * @param vSnap the snapshot to ensure; or NULL for return only 00179 * @param cDelta the allowable change in the heap's object count 00180 * 00181 * @return a new Snapshot 00182 * 00183 * @throws IllegalStateException if the delta does not contain the 00184 * expected amount. The text of the exception will include the 00185 * output of the Snapshots toString() method. 00186 */ 00187 static Snapshot::View ensureHeap(Snapshot::View vSnap = NULL, 00188 int64_t cDelta = 0); 00189 00190 00191 // ----- inner class: Block --------------------------------------------- 00192 00193 public: 00194 /** 00195 * The HeapAnalyzer::Block allows for easily verifying that a block 00196 * of code does not leak memory. 00197 * 00198 * @code 00199 * COH_ENSURE_HEAP 00200 * { 00201 * ... // your code here 00202 * } 00203 * @endcode 00204 */ 00205 class Block 00206 { 00207 // ----- constructors --------------------------------------- 00208 00209 public: 00210 /** 00211 * Construct a ZeroBlock object. 00212 * 00213 * This will automatically capture an initial snapshot 00214 */ 00215 Block() 00216 : m_vSnap(ensureHeap()) 00217 { 00218 } 00219 00220 /** 00221 * Copy constructor for COH_ENSURE_HEAP macro. 00222 */ 00223 Block(const Block& that) 00224 : m_vSnap(that.m_vSnap) 00225 { 00226 that.m_vSnap = NULL; 00227 } 00228 00229 /** 00230 * Destroy a Block object. 00231 * 00232 * This will test that no memory has been leaked 00233 */ 00234 ~Block() COH_NOEXCEPT(false) 00235 { 00236 ensureHeap(m_vSnap); 00237 } 00238 00239 00240 // ----- operators ------------------------------------------ 00241 00242 public: 00243 /* 00244 * Boolean conversion for use in COH_ENSURE_HEAP macro. 00245 * 00246 * @return false if snapshot is held, true otherwise 00247 */ 00248 operator bool() const 00249 { 00250 return m_vSnap == NULL; 00251 } 00252 00253 private: 00254 /** 00255 * Blocked assignment operator. 00256 */ 00257 const Block& operator=(const Block&); 00258 00259 /** 00260 * Blocked dynamic allocation. 00261 */ 00262 static void* operator new(size_t); 00263 00264 00265 // ----- data members --------------------------------------- 00266 00267 protected: 00268 mutable Snapshot::View m_vSnap; // on stack 00269 }; 00270 00271 // ----- friends -------------------------------------------------------- 00272 00273 friend class Object; 00274 }; 00275 00276 COH_CLOSE_NAMESPACE2 00277 00278 00279 /** 00280 * Macro for making more readable HeapAnalyzer::Block code blocks See the 00281 * documentation of Block for a usage example. 00282 * 00283 * @see coherence::lang::HeapAnalyzer::Block 00284 */ 00285 #define COH_ENSURE_HEAP \ 00286 if (coherence::lang::HeapAnalyzer::Block COH_UNIQUE_IDENTIFIER(_coh_heap_) \ 00287 = coherence::lang::HeapAnalyzer::Block()) \ 00288 { \ 00289 COH_THROW(coherence::lang::IllegalStateException::create()); \ 00290 } \ 00291 else 00292 00293 00294 #endif // COH_HEAP_ANALYZER_HPP