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