OLD | NEW |
| (Empty) |
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. | |
112 * | |
113 * This is equivalent to calling ProfilerStartWithOptions(fname, NULL). | |
114 */ | |
115 PERFTOOLS_DLL_DECL int ProfilerStart(const char* fname); | |
116 | |
117 /* Start profiling and write profile into fname. | |
118 * | |
119 * The profiler is configured using the options given by 'options'. | |
120 * Options which are not specified are given default values. | |
121 * | |
122 * 'options' may be NULL, in which case all are given default values. | |
123 * | |
124 * Returns nonzero if profiling was started sucessfully, or zero else. | |
125 */ | |
126 PERFTOOLS_DLL_DECL int ProfilerStartWithOptions( | |
127 const char *fname, const struct ProfilerOptions *options); | |
128 | |
129 /* Stop profiling. Can be started again with ProfilerStart(), but | |
130 * the currently accumulated profiling data will be cleared. | |
131 */ | |
132 PERFTOOLS_DLL_DECL void ProfilerStop(); | |
133 | |
134 /* Flush any currently buffered profiling state to the profile file. | |
135 * Has no effect if the profiler has not been started. | |
136 */ | |
137 PERFTOOLS_DLL_DECL void ProfilerFlush(); | |
138 | |
139 | |
140 /* DEPRECATED: these functions were used to enable/disable profiling | |
141 * in the current thread, but no longer do anything. | |
142 */ | |
143 PERFTOOLS_DLL_DECL void ProfilerEnable(); | |
144 PERFTOOLS_DLL_DECL void ProfilerDisable(); | |
145 | |
146 /* Returns nonzero if profile is currently enabled, zero if it's not. */ | |
147 PERFTOOLS_DLL_DECL int ProfilingIsEnabledForAllThreads(); | |
148 | |
149 /* Routine for registering new threads with the profiler. | |
150 */ | |
151 PERFTOOLS_DLL_DECL void ProfilerRegisterThread(); | |
152 | |
153 /* Stores state about profiler's current status into "*state". */ | |
154 struct ProfilerState { | |
155 int enabled; /* Is profiling currently enabled? */ | |
156 time_t start_time; /* If enabled, when was profiling started? */ | |
157 char profile_name[1024]; /* Name of profile file being written, or '\0' */ | |
158 int samples_gathered; /* Number of samples gathered so far (or 0) */ | |
159 }; | |
160 PERFTOOLS_DLL_DECL void ProfilerGetCurrentState(struct ProfilerState* state); | |
161 | |
162 #ifdef __cplusplus | |
163 } // extern "C" | |
164 #endif | |
165 | |
166 #endif /* BASE_PROFILER_H_ */ | |
OLD | NEW |