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
75extern "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 */
88struct 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 */
116PERFTOOLS_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 */
128PERFTOOLS_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 */
134PERFTOOLS_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 */
139PERFTOOLS_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 */
145PERFTOOLS_DLL_DECL void ProfilerEnable();
146PERFTOOLS_DLL_DECL void ProfilerDisable();
147
148/* Returns nonzero if profile is currently enabled, zero if it's not. */
149PERFTOOLS_DLL_DECL int ProfilingIsEnabledForAllThreads();
150
151/* Routine for registering new threads with the profiler.
152 */
153PERFTOOLS_DLL_DECL void ProfilerRegisterThread();
154
155/* Stores state about profiler's current status into "*state". */
156struct 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};
162PERFTOOLS_DLL_DECL void ProfilerGetCurrentState(struct ProfilerState* state);
163
164#ifdef __cplusplus
165}  // extern "C"
166#endif
167
168#endif  /* BASE_PROFILER_H_ */
169