1 //===-- SBThread.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_SBTHREAD_H 10 #define LLDB_API_SBTHREAD_H 11 12 #include "lldb/API/SBDefines.h" 13 14 #include <cstdio> 15 16 namespace lldb { 17 18 class SBFrame; 19 20 class LLDB_API SBThread { 21 public: 22 enum { 23 eBroadcastBitStackChanged = (1 << 0), 24 eBroadcastBitThreadSuspended = (1 << 1), 25 eBroadcastBitThreadResumed = (1 << 2), 26 eBroadcastBitSelectedFrameChanged = (1 << 3), 27 eBroadcastBitThreadSelected = (1 << 4) 28 }; 29 30 static const char *GetBroadcasterClassName(); 31 32 SBThread(); 33 34 SBThread(const lldb::SBThread &thread); 35 36 SBThread(const lldb::ThreadSP &lldb_object_sp); 37 38 ~SBThread(); 39 40 lldb::SBQueue GetQueue() const; 41 42 explicit operator bool() const; 43 44 bool IsValid() const; 45 46 void Clear(); 47 48 lldb::StopReason GetStopReason(); 49 50 /// Get the number of words associated with the stop reason. 51 /// See also GetStopReasonDataAtIndex(). 52 size_t GetStopReasonDataCount(); 53 54 /// Get information associated with a stop reason. 55 /// 56 /// Breakpoint stop reasons will have data that consists of pairs of 57 /// breakpoint IDs followed by the breakpoint location IDs (they always come 58 /// in pairs). 59 /// 60 /// Stop Reason Count Data Type 61 /// ======================== ===== ========================================= 62 /// eStopReasonNone 0 63 /// eStopReasonTrace 0 64 /// eStopReasonBreakpoint N duple: {breakpoint id, location id} 65 /// eStopReasonWatchpoint 1 watchpoint id 66 /// eStopReasonSignal 1 unix signal number 67 /// eStopReasonException N exception data 68 /// eStopReasonExec 0 69 /// eStopReasonFork 1 pid of the child process 70 /// eStopReasonVFork 1 pid of the child process 71 /// eStopReasonVForkDone 0 72 /// eStopReasonPlanComplete 0 73 uint64_t GetStopReasonDataAtIndex(uint32_t idx); 74 75 bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream); 76 77 SBThreadCollection 78 GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type); 79 80 size_t GetStopDescription(char *dst, size_t dst_len); 81 82 SBValue GetStopReturnValue(); 83 84 lldb::tid_t GetThreadID() const; 85 86 uint32_t GetIndexID() const; 87 88 const char *GetName() const; 89 90 const char *GetQueueName() const; 91 92 lldb::queue_id_t GetQueueID() const; 93 94 bool GetInfoItemByPathAsString(const char *path, SBStream &strm); 95 96 void StepOver(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 97 98 void StepOver(lldb::RunMode stop_other_threads, SBError &error); 99 100 void StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 101 102 void StepInto(const char *target_name, 103 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 104 105 void StepInto(const char *target_name, uint32_t end_line, SBError &error, 106 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 107 108 void StepOut(); 109 110 void StepOut(SBError &error); 111 112 void StepOutOfFrame(SBFrame &frame); 113 114 void StepOutOfFrame(SBFrame &frame, SBError &error); 115 116 void StepInstruction(bool step_over); 117 118 void StepInstruction(bool step_over, SBError &error); 119 120 SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec, 121 uint32_t line); 122 123 SBError StepUsingScriptedThreadPlan(const char *script_class_name); 124 125 SBError StepUsingScriptedThreadPlan(const char *script_class_name, 126 bool resume_immediately); 127 128 SBError StepUsingScriptedThreadPlan(const char *script_class_name, 129 lldb::SBStructuredData &args_data, 130 bool resume_immediately); 131 132 SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line); 133 134 void RunToAddress(lldb::addr_t addr); 135 136 void RunToAddress(lldb::addr_t addr, SBError &error); 137 138 SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value); 139 140 SBError UnwindInnermostExpression(); 141 142 /// LLDB currently supports process centric debugging which means when any 143 /// thread in a process stops, all other threads are stopped. The Suspend() 144 /// call here tells our process to suspend a thread and not let it run when 145 /// the other threads in a process are allowed to run. So when 146 /// SBProcess::Continue() is called, any threads that aren't suspended will 147 /// be allowed to run. If any of the SBThread functions for stepping are 148 /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the 149 /// thread will not be allowed to run and these functions will simply return. 150 /// 151 /// Eventually we plan to add support for thread centric debugging where 152 /// each thread is controlled individually and each thread would broadcast 153 /// its state, but we haven't implemented this yet. 154 /// 155 /// Likewise the SBThread::Resume() call will again allow the thread to run 156 /// when the process is continued. 157 /// 158 /// Suspend() and Resume() functions are not currently reference counted, if 159 /// anyone has the need for them to be reference counted, please let us 160 /// know. 161 bool Suspend(); 162 163 bool Suspend(SBError &error); 164 165 bool Resume(); 166 167 bool Resume(SBError &error); 168 169 bool IsSuspended(); 170 171 bool IsStopped(); 172 173 uint32_t GetNumFrames(); 174 175 lldb::SBFrame GetFrameAtIndex(uint32_t idx); 176 177 lldb::SBFrame GetSelectedFrame(); 178 179 lldb::SBFrame SetSelectedFrame(uint32_t frame_idx); 180 181 static bool EventIsThreadEvent(const SBEvent &event); 182 183 static SBFrame GetStackFrameFromEvent(const SBEvent &event); 184 185 static SBThread GetThreadFromEvent(const SBEvent &event); 186 187 lldb::SBProcess GetProcess(); 188 189 const lldb::SBThread &operator=(const lldb::SBThread &rhs); 190 191 bool operator==(const lldb::SBThread &rhs) const; 192 193 bool operator!=(const lldb::SBThread &rhs) const; 194 195 bool GetDescription(lldb::SBStream &description) const; 196 197 bool GetDescription(lldb::SBStream &description, bool stop_format) const; 198 199 bool GetStatus(lldb::SBStream &status) const; 200 201 SBThread GetExtendedBacktraceThread(const char *type); 202 203 uint32_t GetExtendedBacktraceOriginatingIndexID(); 204 205 SBValue GetCurrentException(); 206 207 SBThread GetCurrentExceptionBacktrace(); 208 209 bool SafeToCallFunctions(); 210 211 SBValue GetSiginfo(); 212 213 private: 214 friend class SBBreakpoint; 215 friend class SBBreakpointLocation; 216 friend class SBBreakpointCallbackBaton; 217 friend class SBExecutionContext; 218 friend class SBFrame; 219 friend class SBProcess; 220 friend class SBDebugger; 221 friend class SBValue; 222 friend class lldb_private::QueueImpl; 223 friend class SBQueueItem; 224 friend class SBThreadPlan; 225 friend class SBTrace; 226 227 void SetThread(const lldb::ThreadSP &lldb_object_sp); 228 229 SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx, 230 lldb_private::ThreadPlan *new_plan); 231 232 lldb::ExecutionContextRefSP m_opaque_sp; 233 234 lldb_private::Thread *operator->(); 235 236 lldb_private::Thread *get(); 237 }; 238 239 } // namespace lldb 240 241 #endif // LLDB_API_SBTHREAD_H 242