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