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 | /// Similar to \a GetDescription() but the format of the description can be |
204 | /// configured via the \p format parameter. See |
205 | /// https://lldb.llvm.org/use/formatting.html for more information on format |
206 | /// strings. |
207 | /// |
208 | /// \param[in] format |
209 | /// The format to use for generating the description. |
210 | /// |
211 | /// \param[out] output |
212 | /// The stream where the description will be written to. |
213 | /// |
214 | /// \return |
215 | /// An error object with an error message in case of failures. |
216 | SBError GetDescriptionWithFormat(const SBFormat &format, SBStream &output); |
217 | |
218 | bool GetStatus(lldb::SBStream &status) const; |
219 | |
220 | SBThread GetExtendedBacktraceThread(const char *type); |
221 | |
222 | uint32_t GetExtendedBacktraceOriginatingIndexID(); |
223 | |
224 | SBValue GetCurrentException(); |
225 | |
226 | SBThread GetCurrentExceptionBacktrace(); |
227 | |
228 | bool SafeToCallFunctions(); |
229 | |
230 | SBValue GetSiginfo(); |
231 | |
232 | private: |
233 | friend class SBBreakpoint; |
234 | friend class SBBreakpointLocation; |
235 | friend class SBBreakpointCallbackBaton; |
236 | friend class SBExecutionContext; |
237 | friend class SBFrame; |
238 | friend class SBProcess; |
239 | friend class SBDebugger; |
240 | friend class SBValue; |
241 | friend class lldb_private::QueueImpl; |
242 | friend class SBQueueItem; |
243 | friend class SBThreadCollection; |
244 | friend class SBThreadPlan; |
245 | friend class SBTrace; |
246 | |
247 | friend class lldb_private::python::SWIGBridge; |
248 | |
249 | SBThread(const lldb::ThreadSP &lldb_object_sp); |
250 | |
251 | void SetThread(const lldb::ThreadSP &lldb_object_sp); |
252 | |
253 | SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx, |
254 | lldb_private::ThreadPlan *new_plan); |
255 | |
256 | lldb::ExecutionContextRefSP m_opaque_sp; |
257 | |
258 | lldb_private::Thread *operator->(); |
259 | |
260 | lldb_private::Thread *get(); |
261 | }; |
262 | |
263 | } // namespace lldb |
264 | |
265 | #endif // LLDB_API_SBTHREAD_H |
266 | |