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