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