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