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