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 
16 namespace lldb {
17 
18 class SBFrame;
19 
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 
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 private:
212  friend class SBBreakpoint;
213  friend class SBBreakpointLocation;
215  friend class SBExecutionContext;
216  friend class SBFrame;
217  friend class SBProcess;
218  friend class SBDebugger;
219  friend class SBValue;
221  friend class SBQueueItem;
222  friend class SBThreadPlan;
223  friend class SBTrace;
224 
225  void SetThread(const lldb::ThreadSP &lldb_object_sp);
226 
227  SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
228  lldb_private::ThreadPlan *new_plan);
229 
230  lldb::ExecutionContextRefSP m_opaque_sp;
231 
232  lldb_private::Thread *operator->();
233 
234  lldb_private::Thread *get();
235 };
236 
237 } // namespace lldb
238 
239 #endif // LLDB_API_SBTHREAD_H
lldb::SBBreakpointLocation
Definition: SBBreakpointLocation.h:17
lldb_private::ExecutionContext
Definition: ExecutionContext.h:292
lldb::SBThread
Definition: SBThread.h:20
SBDefines.h
lldb::SBError
Definition: SBError.h:20
lldb::SBValue
Definition: SBValue.h:21
lldb::SBThreadCollection
Definition: SBThreadCollection.h:16
LLDB_API
#define LLDB_API
Definition: lldb-defines.h:23
lldb::StopReason
StopReason
Thread stop reasons.
Definition: lldb-enumerations.h:239
lldb::SBEvent
Definition: SBEvent.h:21
lldb::SBProcess
Definition: SBProcess.h:23
lldb::addr_t
uint64_t addr_t
Definition: lldb-types.h:83
lldb::SBQueueItem
Definition: SBQueueItem.h:17
lldb::SBExecutionContext
Definition: SBExecutionContext.h:20
lldb::queue_id_t
uint64_t queue_id_t
Definition: lldb-types.h:91
lldb::SBTrace
Definition: SBTrace.h:19
error
static llvm::raw_ostream & error(Stream &strm)
Definition: CommandReturnObject.cpp:17
lldb_private::ThreadPlan
Definition: ThreadPlan.h:282
lldb::SBFrame
Definition: SBFrame.h:17
lldb::SBDebugger
Definition: SBDebugger.h:34
lldb_private::Thread
Definition: Thread.h:60
lldb::SBThreadPlan
Definition: SBThreadPlan.h:18
GetName
static llvm::StringRef GetName(XcodeSDK::Type type)
Definition: XcodeSDK.cpp:21
lldb::SBBreakpointCallbackBaton
Definition: SBBreakpointOptionCommon.h:22
lldb::SBFrame
class LLDB_API SBFrame
Definition: SBDefines.h:48
lldb::operator==
bool LLDB_API operator==(const SBAddress &lhs, const SBAddress &rhs)
Definition: SBAddress.cpp:63
lldb_private::QueueImpl
Definition: SBQueue.cpp:28
lldb_private::operator!=
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:1005
lldb::RunMode
RunMode
Thread Run Modes.
Definition: lldb-enumerations.h:135
lldb::SBThread
class LLDB_API SBThread
Definition: SBDefines.h:75
uint32_t
lldb::SBQueue
Definition: SBQueue.h:19
lldb::SBStructuredData
Definition: SBStructuredData.h:17
lldb::SBBreakpoint
Definition: SBBreakpoint.h:18
lldb::eOnlyDuringStepping
@ eOnlyDuringStepping
Definition: lldb-enumerations.h:135
lldb::SBFileSpec
Definition: SBFileSpec.h:16
lldb::SBThread::m_opaque_sp
lldb::ExecutionContextRefSP m_opaque_sp
Definition: SBThread.h:230
lldb::SBStream
Definition: SBStream.h:18
lldb
Definition: SBAddress.h:15
lldb::tid_t
uint64_t tid_t
Definition: lldb-types.h:86
lldb::InstrumentationRuntimeType
InstrumentationRuntimeType
Definition: lldb-enumerations.h:485