LLVM 19.0.0git
Go to the documentation of this file.
1//===- llvm/Support/TimeProfiler.h - Hierarchical Time Profiler -*- C++ -*-===//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
9// This provides lightweight and dependency-free machinery to trace execution
10// time around arbitrary code. Two API flavors are available.
12// The primary API uses a RAII object to trigger tracing:
14// \code
15// {
16// TimeTraceScope scope("my_event_name");
17// ...my code...
18// }
19// \endcode
21// If the code to be profiled does not have a natural lexical scope then
22// it is also possible to start and end events with respect to an implicit
23// per-thread stack of profiling entries:
25// \code
26// timeTraceProfilerBegin("my_event_name");
27// ...my code...
28// timeTraceProfilerEnd(); // must be called on all control flow paths
29// \endcode
31// Time profiling entries can be given an arbitrary name and, optionally,
32// an arbitrary 'detail' string. The resulting trace will include 'Total'
33// entries summing the time spent for each name. Thus, it's best to choose
34// names to be fairly generic, and rely on the detail field to capture
35// everything else of interest.
37// To avoid lifetime issues name and detail strings are copied into the event
38// entries at their time of creation. Care should be taken to make string
39// construction cheap to prevent 'Heisenperf' effects. In particular, the
40// 'detail' argument may be a string-returning closure:
42// \code
43// int n;
44// {
45// TimeTraceScope scope("my_event_name",
46// [n]() { return (Twine("x=") + Twine(n)).str(); });
47// ...my code...
48// }
49// \endcode
50// The closure will not be called if tracing is disabled. Otherwise, the
51// resulting string will be directly moved into the entry.
53// The main process should begin with a timeTraceProfilerInitialize, and
54// finish with timeTraceProfileWrite and timeTraceProfilerCleanup calls.
55// Each new thread should begin with a timeTraceProfilerInitialize, and
56// finish with a timeTraceProfilerFinishThread call.
58// Timestamps come from std::chrono::stable_clock. Note that threads need
59// not see the same time from that clock, and the resolution may not be
60// the best available.
62// Currently, there are a number of compatible viewers:
63// - chrome://tracing is the original chromium trace viewer.
64// - http://ui.perfetto.dev is the replacement for the above, under active
65// development by Google as part of the 'Perfetto' project.
66// - https://www.speedscope.app/ has also been reported as an option.
68// Future work:
69// - Support akin to LLVM_DEBUG for runtime enable/disable of named tracing
70// families for non-debug builds which wish to support optional tracing.
71// - Evaluate the detail closures at profile write time to avoid
72// stringification costs interfering with tracing.
80#include "llvm/Support/Error.h"
82namespace llvm {
84class raw_pwrite_stream;
86struct TimeTraceProfiler;
87TimeTraceProfiler *getTimeTraceProfilerInstance();
89struct TimeTraceProfilerEntry;
91/// Initialize the time trace profiler.
92/// This sets up the global \p TimeTraceProfilerInstance
93/// variable to be the profiler instance.
94void timeTraceProfilerInitialize(unsigned TimeTraceGranularity,
95 StringRef ProcName);
97/// Cleanup the time trace profiler, if it was initialized.
100/// Finish a time trace profiler running on a worker thread.
103/// Is the time trace profiler enabled, i.e. initialized?
105 return getTimeTraceProfilerInstance() != nullptr;
108/// Write profiling data to output stream.
109/// Data produced is JSON, in Chrome "Trace Event" format, see
110/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
111void timeTraceProfilerWrite(raw_pwrite_stream &OS);
113/// Write profiling data to a file.
114/// The function will write to \p PreferredFileName if provided, if not
115/// then will write to \p FallbackFileName appending .time-trace.
116/// Returns a StringError indicating a failure if the function is
117/// unable to open the file for writing.
118Error timeTraceProfilerWrite(StringRef PreferredFileName,
119 StringRef FallbackFileName);
121/// Manually begin a time section, with the given \p Name and \p Detail.
122/// Profiler copies the string data, so the pointers can be given into
123/// temporaries. Time sections can be hierarchical; every Begin must have a
124/// matching End pair but they can nest.
125TimeTraceProfilerEntry *timeTraceProfilerBegin(StringRef Name,
126 StringRef Detail);
127TimeTraceProfilerEntry *
129 llvm::function_ref<std::string()> Detail);
131/// Manually begin a time section, with the given \p Name and \p Detail.
132/// This starts Async Events having \p Name as a category which is shown
133/// separately from other traces. See
134/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview#heading=h.jh64i9l3vwa1
135/// for more details.
136TimeTraceProfilerEntry *timeTraceAsyncProfilerBegin(StringRef Name,
137 StringRef Detail);
139/// Manually end the last time section.
141void timeTraceProfilerEnd(TimeTraceProfilerEntry *E);
143/// The TimeTraceScope is a helper class to call the begin and end functions
144/// of the time trace profiler. When the object is constructed, it begins
145/// the section; and when it is destroyed, it stops it. If the time profiler
146/// is not initialized, the overhead is a single branch.
149 TimeTraceScope() = delete;
156 if (getTimeTraceProfilerInstance() != nullptr)
158 }
160 if (getTimeTraceProfilerInstance() != nullptr)
161 Entry = timeTraceProfilerBegin(Name, Detail);
162 }
164 if (getTimeTraceProfilerInstance() != nullptr)
165 Entry = timeTraceProfilerBegin(Name, Detail);
166 }
168 if (getTimeTraceProfilerInstance() != nullptr)
170 }
173 TimeTraceProfilerEntry *Entry = nullptr;
176} // end namespace llvm
static GCRegistry::Add< CoreCLRGC > E("coreclr", "CoreCLR-compatible GC")
std::string Name
raw_pwrite_stream & OS
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
The TimeTraceScope is a helper class to call the begin and end functions of the time trace profiler.
Definition: TimeProfiler.h:147
TimeTraceScope(StringRef Name, StringRef Detail)
Definition: TimeProfiler.h:159
TimeTraceScope(const TimeTraceScope &)=delete
TimeTraceScope(StringRef Name)
Definition: TimeProfiler.h:155
TimeTraceScope & operator=(TimeTraceScope &&)=delete
TimeTraceScope(TimeTraceScope &&)=delete
TimeTraceScope(StringRef Name, llvm::function_ref< std::string()> Detail)
Definition: TimeProfiler.h:163
TimeTraceScope & operator=(const TimeTraceScope &)=delete
An efficient, type-erasing, non-owning reference to a callable.
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
void timeTraceProfilerInitialize(unsigned TimeTraceGranularity, StringRef ProcName)
Initialize the time trace profiler.
TimeTraceProfiler * getTimeTraceProfilerInstance()
void timeTraceProfilerFinishThread()
Finish a time trace profiler running on a worker thread.
bool timeTraceProfilerEnabled()
Is the time trace profiler enabled, i.e. initialized?
Definition: TimeProfiler.h:104
void timeTraceProfilerEnd()
Manually end the last time section.
TimeTraceProfilerEntry * timeTraceAsyncProfilerBegin(StringRef Name, StringRef Detail)
Manually begin a time section, with the given Name and Detail.
void timeTraceProfilerCleanup()
Cleanup the time trace profiler, if it was initialized.
void timeTraceProfilerWrite(raw_pwrite_stream &OS)
Write profiling data to output stream.
TimeTraceProfilerEntry * timeTraceProfilerBegin(StringRef Name, StringRef Detail)
Manually begin a time section, with the given Name and Detail.
Represents an open or completed time section entry to be captured.