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 // --- | 30 /* The code has moved to gperftools/. Use that include-directory for |
31 // Author: Sanjay Ghemawat <opensource@google.com> | 31 * new code. |
32 // | 32 */ |
33 // Extra extensions exported by some malloc implementations. These | 33 #include <gperftools/malloc_extension.h> |
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 |