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 interfaces exported by some malloc implementations. These 00034 // interfaces are accessed through a virtual base class so an 00035 // application can link against a malloc that does not implement these 00036 // interfaces, and it will get default versions that do nothing. 00037 00038 #ifndef _GOOGLE_MALLOC_EXTENSION_H__ 00039 #define _GOOGLE_MALLOC_EXTENSION_H__ 00040 00041 #include <stddef.h> 00042 #include <string> 00043 00044 static const int kMallocHistogramSize = 64; 00045 00046 // The default implementations of the following routines do nothing. 00047 class MallocExtension { 00048 public: 00049 virtual ~MallocExtension(); 00050 00051 // Call this very early in the program execution -- say, in a global 00052 // constructor -- to set up parameters and state needed by all 00053 // instrumented malloc implemenatations. One example: this routine 00054 // sets environemnt variables to tell STL to use libc's malloc() 00055 // instead of doing its own memory management. This is safe to call 00056 // multiple times, as long as each time is before threads start up. 00057 static void Initialize(); 00058 00059 // See "verify_memory.h" to see what these routines do 00060 virtual bool VerifyAllMemory(); 00061 virtual bool VerifyNewMemory(void* p); 00062 virtual bool VerifyArrayNewMemory(void* p); 00063 virtual bool VerifyMallocMemory(void* p); 00064 virtual bool MallocMemoryStats(int* blocks, size_t* total, 00065 int histogram[kMallocHistogramSize]); 00066 00067 // Get a human readable description of the current state of the malloc 00068 // data structures. The state is stored as a null-terminated string 00069 // in a prefix of "buffer[0,buffer_length-1]". 00070 // REQUIRES: buffer_length > 0. 00071 virtual void GetStats(char* buffer, int buffer_length); 00072 00073 // Get a string that contains a sample of live objects and the stack 00074 // traces that allocated these objects. The format of the returned 00075 // string is equivalent to the output of the heap profiler and can 00076 // therefore be passed to "pprof". 00077 // 00078 // The generated data is *appended* to "*result". I.e., the old 00079 // contents of "*result" are preserved. 00080 virtual void GetHeapSample(std::string* result); 00081 00082 // Get a string that contains the stack traces that caused growth in 00083 // the addres sspace size. The format of the returned string is 00084 // equivalent to the output of the heap profiler and can therefore 00085 // 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 GetHeapGrowthStacks(std::string* result); 00090 00091 // ------------------------------------------------------------------- 00092 // Control operations for getting and setting malloc implementation 00093 // specific parameters. Some currently useful properties: 00094 // 00095 // generic 00096 // ------- 00097 // "generic.current_allocated_bytes" 00098 // Number of bytes currently allocated by application 00099 // This property is not writable. 00100 // 00101 // "generic.heap_size" 00102 // Number of bytes in the heap == 00103 // current_allocated_bytes + 00104 // fragmentation + 00105 // freed memory regions 00106 // This property is not writable. 00107 // 00108 // tcmalloc 00109 // -------- 00110 // "tcmalloc.max_total_thread_cache_bytes" 00111 // Upper limit on total number of bytes stored across all 00112 // per-thread caches. Default: 16MB. 00113 // 00114 // "tcmalloc.current_total_thread_cache_bytes" 00115 // Number of bytes used across all thread caches. 00116 // This property is not writable. 00117 // 00118 // "tcmalloc.slack_bytes" 00119 // Number of bytes allocated from system, but not currently 00120 // in use by malloced objects. I.e., bytes available for 00121 // allocation without needing more bytes from system. 00122 // This property is not writable. 00123 // 00124 // TODO: Add more properties as necessary 00125 // ------------------------------------------------------------------- 00126 00127 // Get the named "property"'s value. Returns true if the property 00128 // is known. Returns false if the property is not a valid property 00129 // name for the current malloc implementation. 00130 // REQUIRES: property != NULL; value != NULL 00131 virtual bool GetNumericProperty(const char* property, size_t* value); 00132 00133 // Set the named "property"'s value. Returns true if the property 00134 // is known and writable. Returns false if the property is not a 00135 // valid property name for the current malloc implementation, or 00136 // is not writable. 00137 // REQUIRES: property != NULL 00138 virtual bool SetNumericProperty(const char* property, size_t value); 00139 00140 // The current malloc implementation. Always non-NULL. 00141 static MallocExtension* instance(); 00142 00143 // Change the malloc implementation. Typically called by the 00144 // malloc implementation during initialization. 00145 static void Register(MallocExtension* implementation); 00146 00147 protected: 00148 // Get a list of stack traces of sampled allocation points. 00149 // Returns a pointer to a "new[]-ed" result array. 00150 // 00151 // The state is stored as a sequence of adjacent entries 00152 // in the returned array. Each entry has the following form: 00153 // uintptr_t count; // Number of objects with following trace 00154 // uintptr_t size; // Size of object 00155 // uintptr_t depth; // Number of PC values in stack trace 00156 // void* stack[depth]; // PC values that form the stack trace 00157 // 00158 // The list of entries is terminated by a "count" of 0. 00159 // 00160 // It is the responsibility of the caller to "delete[]" the returned array. 00161 // 00162 // May return NULL to indicate no results. 00163 // 00164 // This is an internal extension. Callers should use the more 00165 // convenient "GetHeapSample(string*)" method defined above. 00166 virtual void** ReadStackTraces(); 00167 00168 // Like ReadStackTraces(), but returns stack traces that caused growth 00169 // in the address space size. 00170 virtual void** ReadHeapGrowthStackTraces(); 00171 }; 00172 00173 #endif // _GOOGLE_MALLOC_EXTENSION_H__