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   bool GetStatus(lldb::SBStream &status) const;
204 
205   SBThread GetExtendedBacktraceThread(const char *type);
206 
207   uint32_t GetExtendedBacktraceOriginatingIndexID();
208 
209   SBValue GetCurrentException();
210 
211   SBThread GetCurrentExceptionBacktrace();
212 
213   bool SafeToCallFunctions();
214 
215   SBValue GetSiginfo();
216 
217 private:
218   friend class SBBreakpoint;
219   friend class SBBreakpointLocation;
220   friend class SBBreakpointCallbackBaton;
221   friend class SBExecutionContext;
222   friend class SBFrame;
223   friend class SBProcess;
224   friend class SBDebugger;
225   friend class SBValue;
226   friend class lldb_private::QueueImpl;
227   friend class SBQueueItem;
228   friend class SBThreadCollection;
229   friend class SBThreadPlan;
230   friend class SBTrace;
231 
232   friend class lldb_private::python::SWIGBridge;
233 
234   SBThread(const lldb::ThreadSP &lldb_object_sp);
235 
236   void SetThread(const lldb::ThreadSP &lldb_object_sp);
237 
238   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
239                         lldb_private::ThreadPlan *new_plan);
240 
241   lldb::ExecutionContextRefSP m_opaque_sp;
242 
243   lldb_private::Thread *operator->();
244 
245   lldb_private::Thread *get();
246 };
247 
248 } // namespace lldb
249 
250 #endif // LLDB_API_SBTHREAD_H
251