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   /// 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 
137 protected:
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