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"
15
16namespace lldb {
17
19public:
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
137protected:
138 friend class SBTarget;
139
140 SBTrace(const lldb::TraceSP &trace_sp);
141
143 /// deprecated
145};
146} // namespace lldb
147
148#endif // LLDB_API_SBTRACE_H
static llvm::raw_ostream & error(Stream &strm)
#define LLDB_API
Definition: SBDefines.h:28
lldb::ProcessWP m_opaque_wp
deprecated
Definition: SBTrace.h:144
lldb::TraceSP m_opaque_sp
Definition: SBTrace.h:142
Definition: SBAddress.h:15
std::shared_ptr< lldb_private::Trace > TraceSP
Definition: lldb-forward.h:454
std::weak_ptr< lldb_private::Process > ProcessWP
Definition: lldb-forward.h:390