1 /* Copyright (c) 2005, Google Inc. 2 * All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are 6 * met: 7 * 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above 11 * copyright notice, this list of conditions and the following disclaimer 12 * in the documentation and/or other materials provided with the 13 * distribution. 14 * * Neither the name of Google Inc. nor the names of its 15 * contributors may be used to endorse or promote products derived from 16 * this software without specific prior written permission. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 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. 29 * 30 * --- 31 * Author: Sanjay Ghemawat 32 * 33 * Module for CPU profiling based on periodic pc-sampling. 34 * 35 * For full(er) information, see doc/cpuprofile.html 36 * 37 * This module is linked into your program with 38 * no slowdown caused by this unless you activate the profiler 39 * using one of the following methods: 40 * 41 * 1. Before starting the program, set the environment variable 42 * "PROFILE" to be the name of the file to which the profile 43 * data should be written. 44 * 45 * 2. Programmatically, start and stop the profiler using the 46 * routines "ProfilerStart(filename)" and "ProfilerStop()". 47 * 48 * 49 * (Note: if using linux 2.4 or earlier, only the main thread may be 50 * profiled.) 51 * 52 * Use pprof to view the resulting profile output. 53 * % pprof <path_to_executable> <profile_file_name> 54 * % pprof --gv <path_to_executable> <profile_file_name> 55 * 56 * These functions are thread-safe. 57 */ 58 59 #ifndef BASE_PROFILER_H_ 60 #define BASE_PROFILER_H_ 61 62 #include <time.h> /* For time_t */ 63 64 /* Annoying stuff for windows; makes sure clients can import these functions */ 65 #ifndef PERFTOOLS_DLL_DECL 66 # ifdef _WIN32 67 # define PERFTOOLS_DLL_DECL __declspec(dllimport) 68 # else 69 # define PERFTOOLS_DLL_DECL 70 # endif 71 #endif 72 73 /* All this code should be usable from within C apps. */ 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 /* Profiler options, for use with ProfilerStartWithOptions. To use: 79 * 80 * struct ProfilerOptions options; 81 * memset(&options, 0, sizeof options); 82 * 83 * then fill in fields as needed. 84 * 85 * This structure is intended to be usable from C code, so no constructor 86 * is provided to initialize it. (Use memset as described above). 87 */ 88 struct ProfilerOptions { 89 /* Filter function and argument. 90 * 91 * If filter_in_thread is not NULL, when a profiling tick is delivered 92 * the profiler will call: 93 * 94 * (*filter_in_thread)(filter_in_thread_arg) 95 * 96 * If it returns nonzero, the sample will be included in the profile. 97 * Note that filter_in_thread runs in a signal handler, so must be 98 * async-signal-safe. 99 * 100 * A typical use would be to set up filter results for each thread 101 * in the system before starting the profiler, then to make 102 * filter_in_thread be a very simple function which retrieves those 103 * results in an async-signal-safe way. Retrieval could be done 104 * using thread-specific data, or using a shared data structure that 105 * supports async-signal-safe lookups. 106 */ 107 int (*filter_in_thread)(void *arg); 108 void *filter_in_thread_arg; 109 }; 110 111 /* Start profiling and write profile info into fname, discarding any 112 * existing profiling data in that file. 113 * 114 * This is equivalent to calling ProfilerStartWithOptions(fname, NULL). 115 */ 116 PERFTOOLS_DLL_DECL int ProfilerStart(const char* fname); 117 118 /* Start profiling and write profile into fname, discarding any 119 * existing profiling data in that file. 120 * 121 * The profiler is configured using the options given by 'options'. 122 * Options which are not specified are given default values. 123 * 124 * 'options' may be NULL, in which case all are given default values. 125 * 126 * Returns nonzero if profiling was started sucessfully, or zero else. 127 */ 128 PERFTOOLS_DLL_DECL int ProfilerStartWithOptions( 129 const char *fname, const struct ProfilerOptions *options); 130 131 /* Stop profiling. Can be started again with ProfilerStart(), but 132 * the currently accumulated profiling data will be cleared. 133 */ 134 PERFTOOLS_DLL_DECL void ProfilerStop(); 135 136 /* Flush any currently buffered profiling state to the profile file. 137 * Has no effect if the profiler has not been started. 138 */ 139 PERFTOOLS_DLL_DECL void ProfilerFlush(); 140 141 142 /* DEPRECATED: these functions were used to enable/disable profiling 143 * in the current thread, but no longer do anything. 144 */ 145 PERFTOOLS_DLL_DECL void ProfilerEnable(); 146 PERFTOOLS_DLL_DECL void ProfilerDisable(); 147 148 /* Returns nonzero if profile is currently enabled, zero if it's not. */ 149 PERFTOOLS_DLL_DECL int ProfilingIsEnabledForAllThreads(); 150 151 /* Routine for registering new threads with the profiler. 152 */ 153 PERFTOOLS_DLL_DECL void ProfilerRegisterThread(); 154 155 /* Stores state about profiler's current status into "*state". */ 156 struct ProfilerState { 157 int enabled; /* Is profiling currently enabled? */ 158 time_t start_time; /* If enabled, when was profiling started? */ 159 char profile_name[1024]; /* Name of profile file being written, or '\0' */ 160 int samples_gathered; /* Number of samples gathered so far (or 0) */ 161 }; 162 PERFTOOLS_DLL_DECL void ProfilerGetCurrentState(struct ProfilerState* state); 163 164 #ifdef __cplusplus 165 } // extern "C" 166 #endif 167 168 #endif /* BASE_PROFILER_H_ */ 169
