OLD | NEW |
1 // Copyright (c) 2005, Google Inc. | 1 // Copyright (c) 2005, Google Inc. |
2 // All rights reserved. | 2 // All rights reserved. |
3 // | 3 // |
4 // Redistribution and use in source and binary forms, with or without | 4 // Redistribution and use in source and binary forms, with or without |
5 // modification, are permitted provided that the following conditions are | 5 // modification, are permitted provided that the following conditions are |
6 // met: | 6 // met: |
7 // | 7 // |
8 // * Redistributions of source code must retain the above copyright | 8 // * Redistributions of source code must retain the above copyright |
9 // notice, this list of conditions and the following disclaimer. | 9 // notice, this list of conditions and the following disclaimer. |
10 // * Redistributions in binary form must reproduce the above | 10 // * Redistributions in binary form must reproduce the above |
11 // copyright notice, this list of conditions and the following disclaimer | 11 // copyright notice, this list of conditions and the following disclaimer |
12 // in the documentation and/or other materials provided with the | 12 // in the documentation and/or other materials provided with the |
13 // distribution. | 13 // distribution. |
14 // * Neither the name of Google Inc. nor the names of its | 14 // * Neither the name of Google Inc. nor the names of its |
15 // contributors may be used to endorse or promote products derived from | 15 // contributors may be used to endorse or promote products derived from |
16 // this software without specific prior written permission. | 16 // this software without specific prior written permission. |
17 // | 17 // |
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
29 | 29 |
30 /* The code has moved to gperftools/. Use that include-directory for | 30 // --- |
31 * new code. | 31 // Author: Sanjay Ghemawat <opensource@google.com> |
32 */ | 32 // |
33 #include <gperftools/malloc_extension.h> | 33 // Extra extensions exported by some malloc implementations. These |
| 34 // extensions are accessed through a virtual base class so an |
| 35 // application can link against a malloc that does not implement these |
| 36 // extensions, and it will get default versions that do nothing. |
| 37 // |
| 38 // NOTE FOR C USERS: If you wish to use this functionality from within |
| 39 // a C program, see malloc_extension_c.h. |
| 40 |
| 41 #ifndef BASE_MALLOC_EXTENSION_H_ |
| 42 #define BASE_MALLOC_EXTENSION_H_ |
| 43 |
| 44 #include <stddef.h> |
| 45 // I can't #include config.h in this public API file, but I should |
| 46 // really use configure (and make malloc_extension.h a .in file) to |
| 47 // figure out if the system has stdint.h or not. But I'm lazy, so |
| 48 // for now I'm assuming it's a problem only with MSVC. |
| 49 #ifndef _MSC_VER |
| 50 #include <stdint.h> |
| 51 #endif |
| 52 #include <string> |
| 53 #include <vector> |
| 54 |
| 55 // Annoying stuff for windows -- makes sure clients can import these functions |
| 56 #ifndef PERFTOOLS_DLL_DECL |
| 57 # ifdef _WIN32 |
| 58 # define PERFTOOLS_DLL_DECL __declspec(dllimport) |
| 59 # else |
| 60 # define PERFTOOLS_DLL_DECL |
| 61 # endif |
| 62 #endif |
| 63 |
| 64 static const int kMallocHistogramSize = 64; |
| 65 |
| 66 // One day, we could support other types of writers (perhaps for C?) |
| 67 typedef std::string MallocExtensionWriter; |
| 68 |
| 69 namespace base { |
| 70 struct MallocRange; |
| 71 } |
| 72 |
| 73 // Interface to a pluggable system allocator. |
| 74 class SysAllocator { |
| 75 public: |
| 76 SysAllocator() { |
| 77 } |
| 78 virtual ~SysAllocator(); |
| 79 |
| 80 // Allocates "size"-byte of memory from system aligned with "alignment". |
| 81 // Returns NULL if failed. Otherwise, the returned pointer p up to and |
| 82 // including (p + actual_size -1) have been allocated. |
| 83 virtual void* Alloc(size_t size, size_t *actual_size, size_t alignment) = 0; |
| 84 |
| 85 // Notification that command-line flags have been initialized. |
| 86 virtual void FlagsInitialized() = 0; |
| 87 }; |
| 88 |
| 89 // The default implementations of the following routines do nothing. |
| 90 // All implementations should be thread-safe; the current one |
| 91 // (TCMallocImplementation) is. |
| 92 class PERFTOOLS_DLL_DECL MallocExtension { |
| 93 public: |
| 94 virtual ~MallocExtension(); |
| 95 |
| 96 // Call this very early in the program execution -- say, in a global |
| 97 // constructor -- to set up parameters and state needed by all |
| 98 // instrumented malloc implemenatations. One example: this routine |
| 99 // sets environemnt variables to tell STL to use libc's malloc() |
| 100 // instead of doing its own memory management. This is safe to call |
| 101 // multiple times, as long as each time is before threads start up. |
| 102 static void Initialize(); |
| 103 |
| 104 // See "verify_memory.h" to see what these routines do |
| 105 virtual bool VerifyAllMemory(); |
| 106 virtual bool VerifyNewMemory(void* p); |
| 107 virtual bool VerifyArrayNewMemory(void* p); |
| 108 virtual bool VerifyMallocMemory(void* p); |
| 109 virtual bool MallocMemoryStats(int* blocks, size_t* total, |
| 110 int histogram[kMallocHistogramSize]); |
| 111 |
| 112 // Get a human readable description of the current state of the malloc |
| 113 // data structures. The state is stored as a null-terminated string |
| 114 // in a prefix of "buffer[0,buffer_length-1]". |
| 115 // REQUIRES: buffer_length > 0. |
| 116 virtual void GetStats(char* buffer, int buffer_length); |
| 117 |
| 118 // Outputs to "writer" a sample of live objects and the stack traces |
| 119 // that allocated these objects. The format of the returned output |
| 120 // is equivalent to the output of the heap profiler and can |
| 121 // therefore be passed to "pprof". This function is equivalent to |
| 122 // ReadStackTraces. The main difference is that this function returns |
| 123 // serialized data appropriately formatted for use by the pprof tool. |
| 124 // NOTE: by default, tcmalloc does not do any heap sampling, and this |
| 125 // function will always return an empty sample. To get useful |
| 126 // data from GetHeapSample, you must also set the environment |
| 127 // variable TCMALLOC_SAMPLE_PARAMETER to a value such as 524288. |
| 128 virtual void GetHeapSample(MallocExtensionWriter* writer); |
| 129 |
| 130 // Outputs to "writer" the stack traces that caused growth in the |
| 131 // address space size. The format of the returned output is |
| 132 // equivalent to the output of the heap profiler and can therefore |
| 133 // be passed to "pprof". This function is equivalent to |
| 134 // ReadHeapGrowthStackTraces. The main difference is that this function |
| 135 // returns serialized data appropriately formatted for use by the |
| 136 // pprof tool. (This does not depend on, or require, |
| 137 // TCMALLOC_SAMPLE_PARAMETER.) |
| 138 virtual void GetHeapGrowthStacks(MallocExtensionWriter* writer); |
| 139 |
| 140 // Invokes func(arg, range) for every controlled memory |
| 141 // range. *range is filled in with information about the range. |
| 142 // |
| 143 // This is a best-effort interface useful only for performance |
| 144 // analysis. The implementation may not call func at all. |
| 145 typedef void (RangeFunction)(void*, const base::MallocRange*); |
| 146 virtual void Ranges(void* arg, RangeFunction func); |
| 147 |
| 148 // ------------------------------------------------------------------- |
| 149 // Control operations for getting and setting malloc implementation |
| 150 // specific parameters. Some currently useful properties: |
| 151 // |
| 152 // generic |
| 153 // ------- |
| 154 // "generic.current_allocated_bytes" |
| 155 // Number of bytes currently allocated by application |
| 156 // This property is not writable. |
| 157 // |
| 158 // "generic.heap_size" |
| 159 // Number of bytes in the heap == |
| 160 // current_allocated_bytes + |
| 161 // fragmentation + |
| 162 // freed memory regions |
| 163 // This property is not writable. |
| 164 // |
| 165 // tcmalloc |
| 166 // -------- |
| 167 // "tcmalloc.max_total_thread_cache_bytes" |
| 168 // Upper limit on total number of bytes stored across all |
| 169 // per-thread caches. Default: 16MB. |
| 170 // |
| 171 // "tcmalloc.current_total_thread_cache_bytes" |
| 172 // Number of bytes used across all thread caches. |
| 173 // This property is not writable. |
| 174 // |
| 175 // "tcmalloc.pageheap_free_bytes" |
| 176 // Number of bytes in free, mapped pages in page heap. These |
| 177 // bytes can be used to fulfill allocation requests. They |
| 178 // always count towards virtual memory usage, and unless the |
| 179 // underlying memory is swapped out by the OS, they also count |
| 180 // towards physical memory usage. This property is not writable. |
| 181 // |
| 182 // "tcmalloc.pageheap_unmapped_bytes" |
| 183 // Number of bytes in free, unmapped pages in page heap. |
| 184 // These are bytes that have been released back to the OS, |
| 185 // possibly by one of the MallocExtension "Release" calls. |
| 186 // They can be used to fulfill allocation requests, but |
| 187 // typically incur a page fault. They always count towards |
| 188 // virtual memory usage, and depending on the OS, typically |
| 189 // do not count towards physical memory usage. This property |
| 190 // is not writable. |
| 191 // ------------------------------------------------------------------- |
| 192 |
| 193 // Get the named "property"'s value. Returns true if the property |
| 194 // is known. Returns false if the property is not a valid property |
| 195 // name for the current malloc implementation. |
| 196 // REQUIRES: property != NULL; value != NULL |
| 197 virtual bool GetNumericProperty(const char* property, size_t* value); |
| 198 |
| 199 // Set the named "property"'s value. Returns true if the property |
| 200 // is known and writable. Returns false if the property is not a |
| 201 // valid property name for the current malloc implementation, or |
| 202 // is not writable. |
| 203 // REQUIRES: property != NULL |
| 204 virtual bool SetNumericProperty(const char* property, size_t value); |
| 205 |
| 206 // Mark the current thread as "idle". This routine may optionally |
| 207 // be called by threads as a hint to the malloc implementation that |
| 208 // any thread-specific resources should be released. Note: this may |
| 209 // be an expensive routine, so it should not be called too often. |
| 210 // |
| 211 // Also, if the code that calls this routine will go to sleep for |
| 212 // a while, it should take care to not allocate anything between |
| 213 // the call to this routine and the beginning of the sleep. |
| 214 // |
| 215 // Most malloc implementations ignore this routine. |
| 216 virtual void MarkThreadIdle(); |
| 217 |
| 218 // Mark the current thread as "busy". This routine should be |
| 219 // called after MarkThreadIdle() if the thread will now do more |
| 220 // work. If this method is not called, performance may suffer. |
| 221 // |
| 222 // Most malloc implementations ignore this routine. |
| 223 virtual void MarkThreadBusy(); |
| 224 |
| 225 // Gets the system allocator used by the malloc extension instance. Returns |
| 226 // NULL for malloc implementations that do not support pluggable system |
| 227 // allocators. |
| 228 virtual SysAllocator* GetSystemAllocator(); |
| 229 |
| 230 // Sets the system allocator to the specified. |
| 231 // |
| 232 // Users could register their own system allocators for malloc implementation |
| 233 // that supports pluggable system allocators, such as TCMalloc, by doing: |
| 234 // alloc = new MyOwnSysAllocator(); |
| 235 // MallocExtension::instance()->SetSystemAllocator(alloc); |
| 236 // It's up to users whether to fall back (recommended) to the default |
| 237 // system allocator (use GetSystemAllocator() above) or not. The caller is |
| 238 // responsible to any necessary locking. |
| 239 // See tcmalloc/system-alloc.h for the interface and |
| 240 // tcmalloc/memfs_malloc.cc for the examples. |
| 241 // |
| 242 // It's a no-op for malloc implementations that do not support pluggable |
| 243 // system allocators. |
| 244 virtual void SetSystemAllocator(SysAllocator *a); |
| 245 |
| 246 // Try to release num_bytes of free memory back to the operating |
| 247 // system for reuse. Use this extension with caution -- to get this |
| 248 // memory back may require faulting pages back in by the OS, and |
| 249 // that may be slow. (Currently only implemented in tcmalloc.) |
| 250 virtual void ReleaseToSystem(size_t num_bytes); |
| 251 |
| 252 // Same as ReleaseToSystem() but release as much memory as possible. |
| 253 virtual void ReleaseFreeMemory(); |
| 254 |
| 255 // Sets the rate at which we release unused memory to the system. |
| 256 // Zero means we never release memory back to the system. Increase |
| 257 // this flag to return memory faster; decrease it to return memory |
| 258 // slower. Reasonable rates are in the range [0,10]. (Currently |
| 259 // only implemented in tcmalloc). |
| 260 virtual void SetMemoryReleaseRate(double rate); |
| 261 |
| 262 // Gets the release rate. Returns a value < 0 if unknown. |
| 263 virtual double GetMemoryReleaseRate(); |
| 264 |
| 265 // Returns the estimated number of bytes that will be allocated for |
| 266 // a request of "size" bytes. This is an estimate: an allocation of |
| 267 // SIZE bytes may reserve more bytes, but will never reserve less. |
| 268 // (Currently only implemented in tcmalloc, other implementations |
| 269 // always return SIZE.) |
| 270 // This is equivalent to malloc_good_size() in OS X. |
| 271 virtual size_t GetEstimatedAllocatedSize(size_t size); |
| 272 |
| 273 // Returns the actual number N of bytes reserved by tcmalloc for the |
| 274 // pointer p. The client is allowed to use the range of bytes |
| 275 // [p, p+N) in any way it wishes (i.e. N is the "usable size" of this |
| 276 // allocation). This number may be equal to or greater than the number |
| 277 // of bytes requested when p was allocated. |
| 278 // p must have been allocated by this malloc implementation, |
| 279 // must not be an interior pointer -- that is, must be exactly |
| 280 // the pointer returned to by malloc() et al., not some offset |
| 281 // from that -- and should not have been freed yet. p may be NULL. |
| 282 // (Currently only implemented in tcmalloc; other implementations |
| 283 // will return 0.) |
| 284 // This is equivalent to malloc_size() in OS X, malloc_usable_size() |
| 285 // in glibc, and _msize() for windows. |
| 286 virtual size_t GetAllocatedSize(void* p); |
| 287 |
| 288 // The current malloc implementation. Always non-NULL. |
| 289 static MallocExtension* instance(); |
| 290 |
| 291 // Change the malloc implementation. Typically called by the |
| 292 // malloc implementation during initialization. |
| 293 static void Register(MallocExtension* implementation); |
| 294 |
| 295 // Returns detailed information about malloc's freelists. For each list, |
| 296 // return a FreeListInfo: |
| 297 struct FreeListInfo { |
| 298 size_t min_object_size; |
| 299 size_t max_object_size; |
| 300 size_t total_bytes_free; |
| 301 const char* type; |
| 302 }; |
| 303 // Each item in the vector refers to a different freelist. The lists |
| 304 // are identified by the range of allocations that objects in the |
| 305 // list can satisfy ([min_object_size, max_object_size]) and the |
| 306 // type of freelist (see below). The current size of the list is |
| 307 // returned in total_bytes_free (which count against a processes |
| 308 // resident and virtual size). |
| 309 // |
| 310 // Currently supported types are: |
| 311 // |
| 312 // "tcmalloc.page{_unmapped}" - tcmalloc's page heap. An entry for each size |
| 313 // class in the page heap is returned. Bytes in "page_unmapped" |
| 314 // are no longer backed by physical memory and do not count against |
| 315 // the resident size of a process. |
| 316 // |
| 317 // "tcmalloc.large{_unmapped}" - tcmalloc's list of objects larger |
| 318 // than the largest page heap size class. Only one "large" |
| 319 // entry is returned. There is no upper-bound on the size |
| 320 // of objects in the large free list; this call returns |
| 321 // kint64max for max_object_size. Bytes in |
| 322 // "large_unmapped" are no longer backed by physical memory |
| 323 // and do not count against the resident size of a process. |
| 324 // |
| 325 // "tcmalloc.central" - tcmalloc's central free-list. One entry per |
| 326 // size-class is returned. Never unmapped. |
| 327 // |
| 328 // "debug.free_queue" - free objects queued by the debug allocator |
| 329 // and not returned to tcmalloc. |
| 330 // |
| 331 // "tcmalloc.thread" - tcmalloc's per-thread caches. Never unmapped. |
| 332 virtual void GetFreeListSizes(std::vector<FreeListInfo>* v); |
| 333 |
| 334 // Get a list of stack traces of sampled allocation points. Returns |
| 335 // a pointer to a "new[]-ed" result array, and stores the sample |
| 336 // period in "sample_period". |
| 337 // |
| 338 // The state is stored as a sequence of adjacent entries |
| 339 // in the returned array. Each entry has the following form: |
| 340 // uintptr_t count; // Number of objects with following trace |
| 341 // uintptr_t size; // Total size of objects with following trace |
| 342 // uintptr_t depth; // Number of PC values in stack trace |
| 343 // void* stack[depth]; // PC values that form the stack trace |
| 344 // |
| 345 // The list of entries is terminated by a "count" of 0. |
| 346 // |
| 347 // It is the responsibility of the caller to "delete[]" the returned array. |
| 348 // |
| 349 // May return NULL to indicate no results. |
| 350 // |
| 351 // This is an internal extension. Callers should use the more |
| 352 // convenient "GetHeapSample(string*)" method defined above. |
| 353 virtual void** ReadStackTraces(int* sample_period); |
| 354 |
| 355 // Like ReadStackTraces(), but returns stack traces that caused growth |
| 356 // in the address space size. |
| 357 virtual void** ReadHeapGrowthStackTraces(); |
| 358 }; |
| 359 |
| 360 namespace base { |
| 361 |
| 362 // Information passed per range. More fields may be added later. |
| 363 struct MallocRange { |
| 364 enum Type { |
| 365 INUSE, // Application is using this range |
| 366 FREE, // Range is currently free |
| 367 UNMAPPED, // Backing physical memory has been returned to the OS |
| 368 UNKNOWN, |
| 369 // More enum values may be added in the future |
| 370 }; |
| 371 |
| 372 uintptr_t address; // Address of range |
| 373 size_t length; // Byte length of range |
| 374 Type type; // Type of this range |
| 375 double fraction; // Fraction of range that is being used (0 if !INUSE) |
| 376 |
| 377 // Perhaps add the following: |
| 378 // - stack trace if this range was sampled |
| 379 // - heap growth stack trace if applicable to this range |
| 380 // - age when allocated (for inuse) or freed (if not in use) |
| 381 }; |
| 382 |
| 383 } // namespace base |
| 384 |
| 385 #endif // BASE_MALLOC_EXTENSION_H_ |
OLD | NEW |