1 | //===-- SBTrace.h -----------------------------------------------*- 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 LLDB_API_SBTRACE_H |
10 | #define LLDB_API_SBTRACE_H |
11 | |
12 | #include "lldb/API/SBDefines.h" |
13 | #include "lldb/API/SBError.h" |
14 | #include "lldb/API/SBTraceCursor.h" |
15 | |
16 | namespace lldb { |
17 | |
18 | class LLDB_API SBTrace { |
19 | public: |
20 | /// Default constructor for an invalid Trace object. |
21 | SBTrace(); |
22 | |
23 | /// See SBDebugger::LoadTraceFromFile. |
24 | static SBTrace LoadTraceFromFile(SBError &error, SBDebugger &debugger, |
25 | const SBFileSpec &trace_description_file); |
26 | |
27 | /// Get a \a TraceCursor for the given thread's trace. |
28 | /// |
29 | /// \param[out] error |
30 | /// This will be set with an error in case of failures. |
31 | // |
32 | /// \param[in] thread |
33 | /// The thread to get a \a TraceCursor for. |
34 | // |
35 | /// \return |
36 | /// A \a SBTraceCursor. If the thread is not traced or its trace |
37 | /// information failed to load, an invalid \a SBTraceCursor is returned |
38 | /// and the \p error parameter is set. |
39 | SBTraceCursor CreateNewCursor(SBError &error, SBThread &thread); |
40 | |
41 | /// Save the trace to the specified directory, which will be created if |
42 | /// needed. This will also create a file \a <directory>/trace.json with the |
43 | /// main properties of the trace session, along with others files which |
44 | /// contain the actual trace data. The trace.json file can be used later as |
45 | /// input for the "trace load" command to load the trace in LLDB, or for the |
46 | /// method \a SBDebugger.LoadTraceFromFile(). |
47 | /// |
48 | /// \param[out] error |
49 | /// This will be set with an error in case of failures. |
50 | /// |
51 | /// \param[in] bundle_dir |
52 | /// The directory where the trace files will be saved. |
53 | /// |
54 | /// \param[in] compact |
55 | /// Try not to save to disk information irrelevant to the traced processes. |
56 | /// Each trace plug-in implements this in a different fashion. |
57 | /// |
58 | /// \return |
59 | /// A \a SBFileSpec pointing to the bundle description file. |
60 | SBFileSpec SaveToDisk(SBError &error, const SBFileSpec &bundle_dir, |
61 | bool compact = false); |
62 | |
63 | /// \return |
64 | /// A description of the parameters to use for the \a SBTrace::Start |
65 | /// method, or \b null if the object is invalid. |
66 | const char *GetStartConfigurationHelp(); |
67 | |
68 | /// Start tracing all current and future threads in a live process using a |
69 | /// provided configuration. This is referred as "process tracing" in the |
70 | /// documentation. |
71 | /// |
72 | /// This is equivalent to the command "process trace start". |
73 | /// |
74 | /// This operation fails if it is invoked twice in a row without |
75 | /// first stopping the process trace with \a SBTrace::Stop(). |
76 | /// |
77 | /// If a thread is already being traced explicitly, e.g. with \a |
78 | /// SBTrace::Start(const SBThread &thread, const SBStructuredData |
79 | /// &configuration), it is left unaffected by this operation. |
80 | /// |
81 | /// \param[in] configuration |
82 | /// Dictionary object with custom fields for the corresponding trace |
83 | /// technology. |
84 | /// |
85 | /// Full details for the trace start parameters that can be set can be |
86 | /// retrieved by calling \a SBTrace::GetStartConfigurationHelp(). |
87 | /// |
88 | /// \return |
89 | /// An error explaining any failures. |
90 | SBError Start(const SBStructuredData &configuration); |
91 | |
92 | /// Start tracing a specific thread in a live process using a provided |
93 | /// configuration. This is referred as "thread tracing" in the documentation. |
94 | /// |
95 | /// This is equivalent to the command "thread trace start". |
96 | /// |
97 | /// If the thread is already being traced by a "process tracing" operation, |
98 | /// e.g. with \a SBTrace::Start(const SBStructuredData &configuration), this |
99 | /// operation fails. |
100 | /// |
101 | /// \param[in] configuration |
102 | /// Dictionary object with custom fields for the corresponding trace |
103 | /// technology. |
104 | /// |
105 | /// Full details for the trace start parameters that can be set can be |
106 | /// retrieved by calling \a SBTrace::GetStartConfigurationHelp(). |
107 | /// |
108 | /// \return |
109 | /// An error explaining any failures. |
110 | SBError Start(const SBThread &thread, const SBStructuredData &configuration); |
111 | |
112 | /// Stop tracing all threads in a live process. |
113 | /// |
114 | /// If a "process tracing" operation is active, e.g. \a SBTrace::Start(const |
115 | /// SBStructuredData &configuration), this effectively prevents future threads |
116 | /// from being traced. |
117 | /// |
118 | /// This is equivalent to the command "process trace stop". |
119 | /// |
120 | /// \return |
121 | /// An error explaining any failures. |
122 | SBError Stop(); |
123 | |
124 | /// Stop tracing a specific thread in a live process regardless of whether the |
125 | /// thread was traced explicitly or as part of a "process tracing" operation. |
126 | /// |
127 | /// This is equivalent to the command "thread trace stop". |
128 | /// |
129 | /// \return |
130 | /// An error explaining any failures. |
131 | SBError Stop(const SBThread &thread); |
132 | |
133 | explicit operator bool() const; |
134 | |
135 | bool IsValid(); |
136 | |
137 | protected: |
138 | friend class SBTarget; |
139 | |
140 | SBTrace(const lldb::TraceSP &trace_sp); |
141 | |
142 | lldb::TraceSP m_opaque_sp; |
143 | /// deprecated |
144 | lldb::ProcessWP m_opaque_wp; |
145 | }; |
146 | } // namespace lldb |
147 | |
148 | #endif // LLDB_API_SBTRACE_H |
149 | |