LLDB mainline
SBThread.h
Go to the documentation of this file.
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
16namespace lldb_private {
17namespace python {
18class SWIGBridge;
19}
20} // namespace lldb_private
21
22namespace lldb {
23
24class SBFrame;
25
27public:
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
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
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
232private:
233 friend class SBBreakpoint;
236 friend class SBExecutionContext;
237 friend class SBFrame;
238 friend class SBProcess;
239 friend class SBDebugger;
240 friend class SBValue;
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
257
258 lldb_private::Thread *operator->();
259
261};
262
263} // namespace lldb
264
265#endif // LLDB_API_SBTHREAD_H
static llvm::raw_ostream & error(Stream &strm)
#define LLDB_API
Definition: SBDefines.h:28
static llvm::StringRef GetName(XcodeSDK::Type type)
Definition: XcodeSDK.cpp:21
Class that represents a format string that can be used to generate descriptions of objects like frame...
Definition: SBFormat.h:28
lldb::ExecutionContextRefSP m_opaque_sp
Definition: SBThread.h:256
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
A class that represents a running process on the host machine.
Definition: SBAddress.h:15
std::shared_ptr< lldb_private::Thread > ThreadSP
Definition: lldb-forward.h:441
InstrumentationRuntimeType
uint64_t addr_t
Definition: lldb-types.h:80
StopReason
Thread stop reasons.
class LLDB_API SBFrame
Definition: SBDefines.h:77
bool LLDB_API operator==(const SBAddress &lhs, const SBAddress &rhs)
Definition: SBAddress.cpp:60
RunMode
Thread Run Modes.
@ eOnlyDuringStepping
uint64_t tid_t
Definition: lldb-types.h:84
uint64_t queue_id_t
Definition: lldb-types.h:90
std::shared_ptr< lldb_private::ExecutionContextRef > ExecutionContextRefSP
Definition: lldb-forward.h:345