LLDB
mainline
llvm-project
lldb
include
lldb
API
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
18
class
LLDB_API
SBTrace
{
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
Generated on Fri Aug 19 2022 12:27:23 for LLDB by
1.8.17