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