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 
19 class LLDB_API SBTrace {
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
108