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 <stdio.h> 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 /// eStopReasonPlanComplete 0 70 uint64_t GetStopReasonDataAtIndex(uint32_t idx); 71 72 bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream); 73 74 SBThreadCollection 75 GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type); 76 77 size_t GetStopDescription(char *dst, size_t dst_len); 78 79 SBValue GetStopReturnValue(); 80 81 lldb::tid_t GetThreadID() const; 82 83 uint32_t GetIndexID() const; 84 85 const char *GetName() const; 86 87 const char *GetQueueName() const; 88 89 lldb::queue_id_t GetQueueID() const; 90 91 bool GetInfoItemByPathAsString(const char *path, SBStream &strm); 92 93 void StepOver(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 94 95 void StepOver(lldb::RunMode stop_other_threads, SBError &error); 96 97 void StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 98 99 void StepInto(const char *target_name, 100 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 101 102 void StepInto(const char *target_name, uint32_t end_line, SBError &error, 103 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping); 104 105 void StepOut(); 106 107 void StepOut(SBError &error); 108 109 void StepOutOfFrame(SBFrame &frame); 110 111 void StepOutOfFrame(SBFrame &frame, SBError &error); 112 113 void StepInstruction(bool step_over); 114 115 void StepInstruction(bool step_over, SBError &error); 116 117 SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec, 118 uint32_t line); 119 120 SBError StepUsingScriptedThreadPlan(const char *script_class_name); 121 122 SBError StepUsingScriptedThreadPlan(const char *script_class_name, 123 bool resume_immediately); 124 125 SBError StepUsingScriptedThreadPlan(const char *script_class_name, 126 lldb::SBStructuredData &args_data, 127 bool resume_immediately); 128 129 SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line); 130 131 void RunToAddress(lldb::addr_t addr); 132 133 void RunToAddress(lldb::addr_t addr, SBError &error); 134 135 SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value); 136 137 SBError UnwindInnermostExpression(); 138 139 /// LLDB currently supports process centric debugging which means when any 140 /// thread in a process stops, all other threads are stopped. The Suspend() 141 /// call here tells our process to suspend a thread and not let it run when 142 /// the other threads in a process are allowed to run. So when 143 /// SBProcess::Continue() is called, any threads that aren't suspended will 144 /// be allowed to run. If any of the SBThread functions for stepping are 145 /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the 146 /// thread will not be allowed to run and these functions will simply return. 147 /// 148 /// Eventually we plan to add support for thread centric debugging where 149 /// each thread is controlled individually and each thread would broadcast 150 /// its state, but we haven't implemented this yet. 151 /// 152 /// Likewise the SBThread::Resume() call will again allow the thread to run 153 /// when the process is continued. 154 /// 155 /// Suspend() and Resume() functions are not currently reference counted, if 156 /// anyone has the need for them to be reference counted, please let us 157 /// know. 158 bool Suspend(); 159 160 bool Suspend(SBError &error); 161 162 bool Resume(); 163 164 bool Resume(SBError &error); 165 166 bool IsSuspended(); 167 168 bool IsStopped(); 169 170 uint32_t GetNumFrames(); 171 172 lldb::SBFrame GetFrameAtIndex(uint32_t idx); 173 174 lldb::SBFrame GetSelectedFrame(); 175 176 lldb::SBFrame SetSelectedFrame(uint32_t frame_idx); 177 178 static bool EventIsThreadEvent(const SBEvent &event); 179 180 static SBFrame GetStackFrameFromEvent(const SBEvent &event); 181 182 static SBThread GetThreadFromEvent(const SBEvent &event); 183 184 lldb::SBProcess GetProcess(); 185 186 const lldb::SBThread &operator=(const lldb::SBThread &rhs); 187 188 bool operator==(const lldb::SBThread &rhs) const; 189 190 bool operator!=(const lldb::SBThread &rhs) const; 191 192 bool GetDescription(lldb::SBStream &description) const; 193 194 bool GetDescription(lldb::SBStream &description, bool stop_format) const; 195 196 bool GetStatus(lldb::SBStream &status) const; 197 198 SBThread GetExtendedBacktraceThread(const char *type); 199 200 uint32_t GetExtendedBacktraceOriginatingIndexID(); 201 202 SBValue GetCurrentException(); 203 204 SBThread GetCurrentExceptionBacktrace(); 205 206 bool SafeToCallFunctions(); 207 208 private: 209 friend class SBBreakpoint; 210 friend class SBBreakpointLocation; 211 friend class SBBreakpointCallbackBaton; 212 friend class SBExecutionContext; 213 friend class SBFrame; 214 friend class SBProcess; 215 friend class SBDebugger; 216 friend class SBValue; 217 friend class lldb_private::QueueImpl; 218 friend class SBQueueItem; 219 friend class SBThreadPlan; 220 221 void SetThread(const lldb::ThreadSP &lldb_object_sp); 222 223 SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx, 224 lldb_private::ThreadPlan *new_plan); 225 226 lldb::ExecutionContextRefSP m_opaque_sp; 227 228 lldb_private::Thread *operator->(); 229 230 lldb_private::Thread *get(); 231 }; 232 233 } // namespace lldb 234 235 #endif // LLDB_API_SBTHREAD_H 236