00001 // Copyright (c) 2005, Google Inc. 00002 // All rights reserved. 00003 // 00004 // Redistribution and use in source and binary forms, with or without 00005 // modification, are permitted provided that the following conditions are 00006 // met: 00007 // 00008 // * Redistributions of source code must retain the above copyright 00009 // notice, this list of conditions and the following disclaimer. 00010 // * Redistributions in binary form must reproduce the above 00011 // copyright notice, this list of conditions and the following disclaimer 00012 // in the documentation and/or other materials provided with the 00013 // distribution. 00014 // * Neither the name of Google Inc. nor the names of its 00015 // contributors may be used to endorse or promote products derived from 00016 // this software without specific prior written permission. 00017 // 00018 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 00019 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 00020 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 00021 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 00022 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 00023 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00024 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 00025 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 00026 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00027 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 00028 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00029 00030 // --- 00031 // Author: Sanjay Ghemawat <opensource@google.com> 00032 // 00033 // Extra extensions exported by some malloc implementations. These 00034 // extensions are accessed through a virtual base class so an 00035 // application can link against a malloc that does not implement these 00036 // extensions, and it will get default versions that do nothing. 00037 00038 #ifndef BASE_MALLOC_EXTENSION_H__ 00039 #define BASE_MALLOC_EXTENSION_H__ 00040 00041 #include <stddef.h> 00042 #include <string> 00043 00044 // Annoying stuff for windows -- makes sure clients can import these functions 00045 #ifndef PERFTOOLS_DLL_DECL 00046 # ifdef WIN32 00047 # define PERFTOOLS_DLL_DECL __declspec(dllimport) 00048 # else 00049 # define PERFTOOLS_DLL_DECL 00050 # endif 00051 #endif 00052 00053 static const int kMallocHistogramSize = 64; 00054 00055 // The default implementations of the following routines do nothing. 00056 class PERFTOOLS_DLL_DECL MallocExtension { 00057 public: 00058 virtual ~MallocExtension(); 00059 00060 // Call this very early in the program execution -- say, in a global 00061 // constructor -- to set up parameters and state needed by all 00062 // instrumented malloc implemenatations. One example: this routine 00063 // sets environemnt variables to tell STL to use libc's malloc() 00064 // instead of doing its own memory management. This is safe to call 00065 // multiple times, as long as each time is before threads start up. 00066 static void Initialize(); 00067 00068 // See "verify_memory.h" to see what these routines do 00069 virtual bool VerifyAllMemory(); 00070 virtual bool VerifyNewMemory(void* p); 00071 virtual bool VerifyArrayNewMemory(void* p); 00072 virtual bool VerifyMallocMemory(void* p); 00073 virtual bool MallocMemoryStats(int* blocks, size_t* total, 00074 int histogram[kMallocHistogramSize]); 00075 00076 // Get a human readable description of the current state of the malloc 00077 // data structures. The state is stored as a null-terminated string 00078 // in a prefix of "buffer[0,buffer_length-1]". 00079 // REQUIRES: buffer_length > 0. 00080 virtual void GetStats(char* buffer, int buffer_length); 00081 00082 // Get a string that contains a sample of live objects and the stack 00083 // traces that allocated these objects. The format of the returned 00084 // string is equivalent to the output of the heap profiler and can 00085 // therefore be passed to "pprof". 00086 // 00087 // The generated data is *appended* to "*result". I.e., the old 00088 // contents of "*result" are preserved. 00089 virtual void GetHeapSample(std::string* result); 00090 00091 // Get a string that contains the stack traces that caused growth in 00092 // the addres sspace size. The format of the returned string is 00093 // equivalent to the output of the heap profiler and can therefore 00094 // be passed to "pprof". 00095 // 00096 // The generated data is *appended* to "*result". I.e., the old 00097 // contents of "*result" are preserved. 00098 virtual void GetHeapGrowthStacks(std::string* result); 00099 00100 // ------------------------------------------------------------------- 00101 // Control operations for getting and setting malloc implementation 00102 // specific parameters. Some currently useful properties: 00103 // 00104 // generic 00105 // ------- 00106 // "generic.current_allocated_bytes" 00107 // Number of bytes currently allocated by application 00108 // This property is not writable. 00109 // 00110 // "generic.heap_size" 00111 // Number of bytes in the heap == 00112 // current_allocated_bytes + 00113 // fragmentation + 00114 // freed memory regions 00115 // This property is not writable. 00116 // 00117 // tcmalloc 00118 // -------- 00119 // "tcmalloc.max_total_thread_cache_bytes" 00120 // Upper limit on total number of bytes stored across all 00121 // per-thread caches. Default: 16MB. 00122 // 00123 // "tcmalloc.current_total_thread_cache_bytes" 00124 // Number of bytes used across all thread caches. 00125 // This property is not writable. 00126 // 00127 // "tcmalloc.slack_bytes" 00128 // Number of bytes allocated from system, but not currently 00129 // in use by malloced objects. I.e., bytes available for 00130 // allocation without needing more bytes from system. 00131 // This property is not writable. 00132 // 00133 // TODO: Add more properties as necessary 00134 // ------------------------------------------------------------------- 00135 00136 // Get the named "property"'s value. Returns true if the property 00137 // is known. Returns false if the property is not a valid property 00138 // name for the current malloc implementation. 00139 // REQUIRES: property != NULL; value != NULL 00140 virtual bool GetNumericProperty(const char* property, size_t* value); 00141 00142 // Set the named "property"'s value. Returns true if the property 00143 // is known and writable. Returns false if the property is not a 00144 // valid property name for the current malloc implementation, or 00145 // is not writable. 00146 // REQUIRES: property != NULL 00147 virtual bool SetNumericProperty(const char* property, size_t value); 00148 00149 // Mark the current thread as "idle". This routine may optionally 00150 // be called by threads as a hint to the malloc implementation that 00151 // any thread-specific resources should be released. Note: this may 00152 // be an expensive routine, so it should not be called too often. 00153 // 00154 // Also, if the code that calls this routine will go to sleep for 00155 // a while, it should take care to not allocate anything between 00156 // the call to this routine and the beginning of the sleep. 00157 // 00158 // Most malloc implementations ignore this routine. 00159 virtual void MarkThreadIdle(); 00160 00161 // Try to free memory back to the operating system for reuse. Only 00162 // use this extension if the application has recently freed a lot of 00163 // memory, and does not anticipate using it again for a long time -- 00164 // to get this memory back may require faulting pages back in by the 00165 // OS, and that may be slow. (Currently only implemented in 00166 // tcmalloc.) 00167 virtual void ReleaseFreeMemory(); 00168 00169 // The current malloc implementation. Always non-NULL. 00170 static MallocExtension* instance(); 00171 00172 // Change the malloc implementation. Typically called by the 00173 // malloc implementation during initialization. 00174 static void Register(MallocExtension* implementation); 00175 00176 protected: 00177 // Get a list of stack traces of sampled allocation points. 00178 // Returns a pointer to a "new[]-ed" result array. 00179 // 00180 // The state is stored as a sequence of adjacent entries 00181 // in the returned array. Each entry has the following form: 00182 // uintptr_t count; // Number of objects with following trace 00183 // uintptr_t size; // Size of object 00184 // uintptr_t depth; // Number of PC values in stack trace 00185 // void* stack[depth]; // PC values that form the stack trace 00186 // 00187 // The list of entries is terminated by a "count" of 0. 00188 // 00189 // It is the responsibility of the caller to "delete[]" the returned array. 00190 // 00191 // May return NULL to indicate no results. 00192 // 00193 // This is an internal extension. Callers should use the more 00194 // convenient "GetHeapSample(string*)" method defined above. 00195 virtual void** ReadStackTraces(); 00196 00197 // Like ReadStackTraces(), but returns stack traces that caused growth 00198 // in the address space size. 00199 virtual void** ReadHeapGrowthStackTraces(); 00200 }; 00201 00202 #endif // BASE_MALLOC_EXTENSION_H__