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_SBThread_h_
10 #define LLDB_SBThread_h_
11 
12 #include "lldb/API/SBDefines.h"
13 
14 #include <stdio.h>
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  /// eStopReasonPlanComplete 0
70  uint64_t GetStopReasonDataAtIndex(uint32_t idx);
71 
72  bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream);
73 
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 JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line);
126 
127  void RunToAddress(lldb::addr_t addr);
128 
129  void RunToAddress(lldb::addr_t addr, SBError &error);
130 
131  SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value);
132 
133  SBError UnwindInnermostExpression();
134 
135  /// LLDB currently supports process centric debugging which means when any
136  /// thread in a process stops, all other threads are stopped. The Suspend()
137  /// call here tells our process to suspend a thread and not let it run when
138  /// the other threads in a process are allowed to run. So when
139  /// SBProcess::Continue() is called, any threads that aren't suspended will
140  /// be allowed to run. If any of the SBThread functions for stepping are
141  /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
142  /// thread will not be allowed to run and these functions will simply return.
143  ///
144  /// Eventually we plan to add support for thread centric debugging where
145  /// each thread is controlled individually and each thread would broadcast
146  /// its state, but we haven't implemented this yet.
147  ///
148  /// Likewise the SBThread::Resume() call will again allow the thread to run
149  /// when the process is continued.
150  ///
151  /// Suspend() and Resume() functions are not currently reference counted, if
152  /// anyone has the need for them to be reference counted, please let us
153  /// know.
154  bool Suspend();
155 
156  bool Suspend(SBError &error);
157 
158  bool Resume();
159 
160  bool Resume(SBError &error);
161 
162  bool IsSuspended();
163 
164  bool IsStopped();
165 
166  uint32_t GetNumFrames();
167 
168  lldb::SBFrame GetFrameAtIndex(uint32_t idx);
169 
170  lldb::SBFrame GetSelectedFrame();
171 
172  lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
173 
174  static bool EventIsThreadEvent(const SBEvent &event);
175 
176  static SBFrame GetStackFrameFromEvent(const SBEvent &event);
177 
178  static SBThread GetThreadFromEvent(const SBEvent &event);
179 
180  lldb::SBProcess GetProcess();
181 
182  const lldb::SBThread &operator=(const lldb::SBThread &rhs);
183 
184  bool operator==(const lldb::SBThread &rhs) const;
185 
186  bool operator!=(const lldb::SBThread &rhs) const;
187 
188  bool GetDescription(lldb::SBStream &description) const;
189 
190  bool GetDescription(lldb::SBStream &description, bool stop_format) const;
191 
192  bool GetStatus(lldb::SBStream &status) const;
193 
194  SBThread GetExtendedBacktraceThread(const char *type);
195 
196  uint32_t GetExtendedBacktraceOriginatingIndexID();
197 
198  SBValue GetCurrentException();
199 
200  SBThread GetCurrentExceptionBacktrace();
201 
202  bool SafeToCallFunctions();
203 
204 private:
205  friend class SBBreakpoint;
206  friend class SBBreakpointLocation;
208  friend class SBExecutionContext;
209  friend class SBFrame;
210  friend class SBProcess;
211  friend class SBDebugger;
212  friend class SBValue;
214  friend class SBQueueItem;
215  friend class SBThreadPlan;
216 
217  void SetThread(const lldb::ThreadSP &lldb_object_sp);
218 
219  SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
220  lldb_private::ThreadPlan *new_plan);
221 
222  lldb::ExecutionContextRefSP m_opaque_sp;
223 
224  lldb_private::Thread *operator->();
225 
226  lldb_private::Thread *get();
227 };
228 
229 } // namespace lldb
230 
231 #endif // LLDB_SBThread_h_
bool LLDB_API operator==(const SBAddress &lhs, const SBAddress &rhs)
Definition: SBAddress.cpp:66
class LLDB_API SBFrame
Definition: SBDefines.h:46
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
InstrumentationRuntimeType
uint64_t tid_t
Definition: lldb-types.h:86
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:979
uint64_t queue_id_t
Definition: lldb-types.h:91
#define LLDB_API
Definition: lldb-defines.h:23
uint64_t addr_t
Definition: lldb-types.h:83
Definition: SBAddress.h:15
class LLDB_API SBThread
Definition: SBDefines.h:73