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