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 namespace lldb {
16 
17 class LLDB_API SBTrace {
18 public:
19   /// Default constructor for an invalid Trace object.
20   SBTrace();
21 
22   SBTrace(const lldb::TraceSP &trace_sp);
23 
24   /// See SBDebugger::LoadTraceFromFile.
25   static SBTrace LoadTraceFromFile(SBError &error, SBDebugger &debugger,
26                                    const SBFileSpec &trace_description_file);
27 
28   /// Save the trace to the specified directory, which will be created if
29   /// needed. This will also create a a file \a <directory>/trace.json with the
30   /// main properties of the trace session, along with others files which
31   /// contain the actual trace data. The trace.json file can be used later as
32   /// input for the "trace load" command to load the trace in LLDB, or for the
33   /// method \a SBDebugger.LoadTraceFromFile().
34   ///
35   /// \param[out] error
36   ///   This will be set with an error in case of failures.
37   ///
38   /// \param[in] directory
39   ///   The directory where the trace files will be saved.
40   ///
41   /// \param[in] compact
42   ///   Try not to save to disk information irrelevant to the traced processes.
43   ///   Each trace plug-in implements this in a different fashion.
44   ///
45   /// \return
46   ///   A \a SBFileSpec pointing to the bundle description file.
47   SBFileSpec SaveToDisk(SBError &error, const SBFileSpec &bundle_dir,
48                         bool compact = false);
49 
50   /// \return
51   ///     A description of the parameters to use for the \a SBTrace::Start
52   ///     method, or \b null if the object is invalid.
53   const char *GetStartConfigurationHelp();
54 
55   /// Start tracing all current and future threads in a live process using a
56   /// provided configuration. This is referred as "process tracing" in the
57   /// documentation.
58   ///
59   /// This is equivalent to the command "process trace start".
60   ///
61   /// This operation fails if it is invoked twice in a row without
62   /// first stopping the process trace with \a SBTrace::Stop().
63   ///
64   /// If a thread is already being traced explicitly, e.g. with \a
65   /// SBTrace::Start(const SBThread &thread, const SBStructuredData
66   /// &configuration), it is left unaffected by this operation.
67   ///
68   /// \param[in] configuration
69   ///     Dictionary object with custom fields for the corresponding trace
70   ///     technology.
71   ///
72   ///     Full details for the trace start parameters that can be set can be
73   ///     retrieved by calling \a SBTrace::GetStartConfigurationHelp().
74   ///
75   /// \return
76   ///     An error explaining any failures.
77   SBError Start(const SBStructuredData &configuration);
78 
79   /// Start tracing a specific thread in a live process using a provided
80   /// configuration. This is referred as "thread tracing" in the documentation.
81   ///
82   /// This is equivalent to the command "thread trace start".
83   ///
84   /// If the thread is already being traced by a "process tracing" operation,
85   /// e.g. with \a SBTrace::Start(const SBStructuredData &configuration), this
86   /// operation fails.
87   ///
88   /// \param[in] configuration
89   ///     Dictionary object with custom fields for the corresponding trace
90   ///     technology.
91   ///
92   ///     Full details for the trace start parameters that can be set can be
93   ///     retrieved by calling \a SBTrace::GetStartConfigurationHelp().
94   ///
95   /// \return
96   ///     An error explaining any failures.
97   SBError Start(const SBThread &thread, const SBStructuredData &configuration);
98 
99   /// Stop tracing all threads in a live process.
100   ///
101   /// If a "process tracing" operation is active, e.g. \a SBTrace::Start(const
102   /// SBStructuredData &configuration), this effectively prevents future threads
103   /// from being traced.
104   ///
105   /// This is equivalent to the command "process trace stop".
106   ///
107   /// \return
108   ///     An error explaining any failures.
109   SBError Stop();
110 
111   /// Stop tracing a specific thread in a live process regardless of whether the
112   /// thread was traced explicitly or as part of a "process tracing" operation.
113   ///
114   /// This is equivalent to the command "thread trace stop".
115   ///
116   /// \return
117   ///     An error explaining any failures.
118   SBError Stop(const SBThread &thread);
119 
120   explicit operator bool() const;
121 
122   bool IsValid();
123 
124 protected:
125   lldb::TraceSP m_opaque_sp;
126   /// deprecated
127   lldb::ProcessWP m_opaque_wp;
128 };
129 } // namespace lldb
130 
131 #endif // LLDB_API_SBTRACE_H
132