1//===- llvm/Support/TimeProfiler.h - Hierarchical Time Profiler -*- C++ -*-===//
2//
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
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLVM_SUPPORT_TIMEPROFILER_H
10#define LLVM_SUPPORT_TIMEPROFILER_H
11
12#include "llvm/Support/Error.h"
13#include "llvm/Support/raw_ostream.h"
14
15namespace llvm {
16
17struct TimeTraceProfiler;
18TimeTraceProfiler *getTimeTraceProfilerInstance();
19
20/// Initialize the time trace profiler.
21/// This sets up the global \p TimeTraceProfilerInstance
22/// variable to be the profiler instance.
23void timeTraceProfilerInitialize(unsigned TimeTraceGranularity,
24 StringRef ProcName);
25
26/// Cleanup the time trace profiler, if it was initialized.
27void timeTraceProfilerCleanup();
28
29/// Finish a time trace profiler running on a worker thread.
30void timeTraceProfilerFinishThread();
31
32/// Is the time trace profiler enabled, i.e. initialized?
33inline bool timeTraceProfilerEnabled() {
34 return getTimeTraceProfilerInstance() != nullptr;
35}
36
37/// Write profiling data to output stream.
38/// Data produced is JSON, in Chrome "Trace Event" format, see
39/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
40void timeTraceProfilerWrite(raw_pwrite_stream &OS);
41
42/// Write profiling data to a file.
43/// The function will write to \p PreferredFileName if provided, if not
44/// then will write to \p FallbackFileName appending .time-trace.
45/// Returns a StringError indicating a failure if the function is
46/// unable to open the file for writing.
47Error timeTraceProfilerWrite(StringRef PreferredFileName,
48 StringRef FallbackFileName);
49
50/// Manually begin a time section, with the given \p Name and \p Detail.
51/// Profiler copies the string data, so the pointers can be given into
52/// temporaries. Time sections can be hierarchical; every Begin must have a
53/// matching End pair but they can nest.
54void timeTraceProfilerBegin(StringRef Name, StringRef Detail);
55void timeTraceProfilerBegin(StringRef Name,
56 llvm::function_ref<std::string()> Detail);
57
58/// Manually end the last time section.
59void timeTraceProfilerEnd();
60
61/// The TimeTraceScope is a helper class to call the begin and end functions
62/// of the time trace profiler. When the object is constructed, it begins
63/// the section; and when it is destroyed, it stops it. If the time profiler
64/// is not initialized, the overhead is a single branch.
65struct TimeTraceScope {
66
67 TimeTraceScope() = delete;
68 TimeTraceScope(const TimeTraceScope &) = delete;
69 TimeTraceScope &operator=(const TimeTraceScope &) = delete;
70 TimeTraceScope(TimeTraceScope &&) = delete;
71 TimeTraceScope &operator=(TimeTraceScope &&) = delete;
72
73 TimeTraceScope(StringRef Name) {
74 if (getTimeTraceProfilerInstance() != nullptr)
75 timeTraceProfilerBegin(Name, StringRef(""));
76 }
77 TimeTraceScope(StringRef Name, StringRef Detail) {
78 if (getTimeTraceProfilerInstance() != nullptr)
79 timeTraceProfilerBegin(Name, Detail);
80 }
81 TimeTraceScope(StringRef Name, llvm::function_ref<std::string()> Detail) {
82 if (getTimeTraceProfilerInstance() != nullptr)
83 timeTraceProfilerBegin(Name, Detail);
84 }
85 ~TimeTraceScope() {
86 if (getTimeTraceProfilerInstance() != nullptr)
87 timeTraceProfilerEnd();
88 }
89};
90
91} // end namespace llvm
92
93#endif
94