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
16namespace lldb {
17
18class LLDB_API SBTrace {
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
142  lldb::TraceSP m_opaque_sp;
143  /// deprecated
144  lldb::ProcessWP m_opaque_wp;
145};
146} // namespace lldb
147
148#endif // LLDB_API_SBTRACE_H
149