00001 /* 00002 * HeapAnalyzer.hpp 00003 * 00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_HEAP_ANALYZER_HPP 00017 #define COH_HEAP_ANALYZER_HPP 00018 00019 #include "coherence/lang/interface_spec.hpp" 00020 #include "coherence/lang/Object.hpp" 00021 #include "coherence/lang/TypedHandle.hpp" 00022 00023 COH_OPEN_NAMESPACE2(coherence,lang) 00024 00025 00026 /** 00027 * HeapAnalyzer provides a base diagnostics interface for tracking heap usage. 00028 * 00029 * There is at most one HeapAnalyzer registered with the system for the 00030 * lifetime of the process. The HeapAnalyzer implementation may be specified 00031 * via the "tangosol.coherence.heap.analyzer" system property. The property 00032 * can be set to one of the following values: 00033 * <ul> 00034 * <li>none No heap analysis will be performed.</li> 00035 * <li>object The coherence::lang::ObjectCountHeapAnalyzer will be used.</li> 00036 * <li>class The coherence::lang::ClassBasedHeapAnalyzer will be used.</li> 00037 * <li>alloc The coherence::lang::ClassBasedHeapAnalyzer will be used, 00038 * in allocation analysis mode.</li> 00039 * <li>[custom] The name of a class registered with the SystemClassLoader.</li> 00040 * </ul> 00041 * 00042 * In the case where a custom class is specified, it must implement this 00043 * interface. The custom analyzer will be initialized as soon as the class 00044 * is registered with the SystemClassLoader. As static initialization order 00045 * cannot be guaranteed, this custom analyzer will not be notified of managed 00046 * objects created earlier in the static initialization order. 00047 * 00048 * The active analyzer may be obtained from the System::getHeapAnalyzer() 00049 * method. 00050 * 00051 * The HeapAnalyzer and Snapshot interfaces are intentionally narrow. 00052 * Implementations are expected to provide useful information via the toStream 00053 * method, as well as by possibly augmenting the interfaces. The minimal 00054 * interface is sufficient for detecting memory leaks. 00055 * 00056 * HeapAnalyzer::Snapshot::View vSnap = hAnalyzer->capture(); 00057 * ... 00058 * ... 00059 * std::cout << "Heap changed by: " << hAnalyzer->delta(vSnap) << std::endl; 00060 * 00061 * @see ObjectCountHeapAnalyzer 00062 * @see ClassBasedHeapAnalyzer 00063 * 00064 * @author mf 2008.04.27 00065 */ 00066 class COH_EXPORT HeapAnalyzer 00067 : public interface_spec<HeapAnalyzer> 00068 { 00069 // ----- nested interface: Snapshot ------------------------------------- 00070 00071 public: 00072 /** 00073 * Snapshot provides a abstract mechanism for comparing successive 00074 * heap analysis points. 00075 */ 00076 class COH_EXPORT Snapshot 00077 : public interface_spec<Snapshot> 00078 { 00079 // ----- Snapshot interface --------------------------------- 00080 00081 public: 00082 /** 00083 * Return the number of registered objects reflected by this 00084 * snapshot. 00085 * 00086 * @return the number of registered objects 00087 */ 00088 virtual int64_t getObjectCount() const = 0; 00089 00090 /** 00091 * Return the result of "subtracting" the supplied Snapshot 00092 * from this Snapshot. 00093 * 00094 * @param vThat the snapshot to compare against 00095 * 00096 * @return the delta between two snapshots 00097 */ 00098 virtual Snapshot::View delta(Snapshot::View vThat) const = 0; 00099 }; 00100 00101 00102 // ----- HeapAnalyzer interface ----------------------------------------- 00103 00104 public: 00105 /** 00106 * Capture a Snapshot of the current state of the heap. 00107 * 00108 * Note, when performing captures in a loop, and assigning the captured 00109 * snapshot to a handle referencing a snapshot, it is advisable to 00110 * NULL out the handle first, so as to avoid the new snapshot including 00111 * the "cost" of snapshot it is about to replace. 00112 * 00113 * @return a Snapshot of the current state of the heap. 00114 */ 00115 virtual Snapshot::View capture() const = 0; 00116 00117 /** 00118 * Compute the delta between the supplied Snapshot and the current heap 00119 * state. 00120 * 00121 * @param vThat the snapshot to compare against. 00122 * 00123 * @return a snapshot containing the delta 00124 */ 00125 virtual Snapshot::View delta(Snapshot::View vThat) const = 0; 00126 00127 /** 00128 * Return the number of registered objects. 00129 * 00130 * @return the number of registered objects 00131 */ 00132 virtual int64_t getObjectCount() const = 0; 00133 00134 protected: 00135 /** 00136 * Register a newly created Object with the system. 00137 * 00138 * This method is called automatically by coherence::lang::Object once 00139 * the Object has finished construction. 00140 * 00141 * @param o the newly created Object. 00142 */ 00143 virtual void registerObject(const Object& o) = 0; 00144 00145 /** 00146 * Unregister an Object with the system. 00147 * 00148 * This method is called automatically by coherence::lang::Object 00149 * just prior to the deletion of the Object. No new handles or views 00150 * may be created to the object. 00151 * 00152 * @param o the Object to unregister 00153 */ 00154 virtual void unregisterObject(const Object& o) = 0; 00155 00156 00157 // ----- static helper methods ------------------------------------------ 00158 00159 public: 00160 /** 00161 * Ensure that the delta between the current heap and the supplied 00162 * snapshot is as expected. 00163 * 00164 * This method can be used to perform quick memory leak assertions. 00165 * 00166 * @code 00167 * HeapAnalyzer::Snapshot::View vSnapStart = HeapAnalyzer::ensureHeap(); 00168 * ... 00169 * ... 00170 * HeapAnalyzer::ensureHeap(vSnapStart); 00171 * @endcode 00172 * 00173 * @param vSnap the snapshot to ensure; or NULL for return only 00174 * @param cDelta the allowable change in the heap's object count 00175 * 00176 * @return a new Snapshot 00177 * 00178 * @throws IllegalStateException if the delta does not contain the 00179 * expected amount. The text of the exception will include the 00180 * output of the Snapshots toStream() method. 00181 */ 00182 static Snapshot::View ensureHeap(Snapshot::View vSnap = NULL, 00183 int64_t cDelta = 0); 00184 00185 // ----- friends -------------------------------------------------------- 00186 00187 friend class Object; 00188 }; 00189 00190 COH_CLOSE_NAMESPACE2 00191 00192 #endif // COH_HEAP_ANALYZER_HPP