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 
15 class TraceImpl;
16 
17 namespace lldb {
18 
20 public:
21  /// Default constructor for an invalid Trace object.
22  SBTrace();
23 
24  SBTrace(const lldb::TraceSP &trace_sp);
25 
26  /// \return
27  /// A description of the parameters to use for the \a SBTrace::Start
28  /// method, or \b null if the object is invalid.
29  const char *GetStartConfigurationHelp();
30 
31  /// Start tracing all current and future threads in a live process using a
32  /// provided configuration. This is referred as "process tracing" in the
33  /// documentation.
34  ///
35  /// This is equivalent to the command "process trace start".
36  ///
37  /// This operation fails if it is invoked twice in a row without
38  /// first stopping the process trace with \a SBTrace::Stop().
39  ///
40  /// If a thread is already being traced explicitly, e.g. with \a
41  /// SBTrace::Start(const SBThread &thread, const SBStructuredData
42  /// &configuration), it is left unaffected by this operation.
43  ///
44  /// \param[in] configuration
45  /// Dictionary object with custom fields for the corresponding trace
46  /// technology.
47  ///
48  /// Full details for the trace start parameters that can be set can be
49  /// retrieved by calling \a SBTrace::GetStartConfigurationHelp().
50  ///
51  /// \return
52  /// An error explaining any failures.
53  SBError Start(const SBStructuredData &configuration);
54 
55  /// Start tracing a specific thread in a live process using a provided
56  /// configuration. This is referred as "thread tracing" in the documentation.
57  ///
58  /// This is equivalent to the command "thread trace start".
59  ///
60  /// If the thread is already being traced by a "process tracing" operation,
61  /// e.g. with \a SBTrace::Start(const SBStructuredData &configuration), this
62  /// operation fails.
63  ///
64  /// \param[in] configuration
65  /// Dictionary object with custom fields for the corresponding trace
66  /// technology.
67  ///
68  /// Full details for the trace start parameters that can be set can be
69  /// retrieved by calling \a SBTrace::GetStartConfigurationHelp().
70  ///
71  /// \return
72  /// An error explaining any failures.
73  SBError Start(const SBThread &thread, const SBStructuredData &configuration);
74 
75  /// Stop tracing all threads in a live process.
76  ///
77  /// If a "process tracing" operation is active, e.g. \a SBTrace::Start(const
78  /// SBStructuredData &configuration), this effectively prevents future threads
79  /// from being traced.
80  ///
81  /// This is equivalent to the command "process trace stop".
82  ///
83  /// \return
84  /// An error explaining any failures.
85  SBError Stop();
86 
87  /// Stop tracing a specific thread in a live process regardless of whether the
88  /// thread was traced explicitly or as part of a "process tracing" operation.
89  ///
90  /// This is equivalent to the command "thread trace stop".
91  ///
92  /// \return
93  /// An error explaining any failures.
94  SBError Stop(const SBThread &thread);
95 
96  explicit operator bool() const;
97 
98  bool IsValid();
99 
100 protected:
101  lldb::TraceSP m_opaque_sp;
102  /// deprecated
103  lldb::ProcessWP m_opaque_wp;
104 };
105 } // namespace lldb
106 
107 #endif // LLDB_API_SBTRACE_H
lldb::SBThread
Definition: SBThread.h:20
lldb::SBTrace::m_opaque_sp
lldb::TraceSP m_opaque_sp
Definition: SBTrace.h:101
SBDefines.h
lldb::SBError
Definition: SBError.h:20
lldb::SBTrace::m_opaque_wp
lldb::ProcessWP m_opaque_wp
deprecated
Definition: SBTrace.h:103
LLDB_API
#define LLDB_API
Definition: lldb-defines.h:23
lldb::SBTrace
Definition: SBTrace.h:19
lldb::SBStructuredData
Definition: SBStructuredData.h:17
lldb::SBTrace
class LLDB_API SBTrace
Definition: SBDefines.h:78
lldb
Definition: SBAddress.h:15
SBError.h