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 
20 class LLDB_API SBThread {
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 
77   SBThreadCollection
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   SBValue GetSiginfo();
212 
213 private:
214   friend class SBBreakpoint;
215   friend class SBBreakpointLocation;
216   friend class SBBreakpointCallbackBaton;
217   friend class SBExecutionContext;
218   friend class SBFrame;
219   friend class SBProcess;
220   friend class SBDebugger;
221   friend class SBValue;
222   friend class lldb_private::QueueImpl;
223   friend class SBQueueItem;
224   friend class SBThreadPlan;
225   friend class SBTrace;
226 
227   void SetThread(const lldb::ThreadSP &lldb_object_sp);
228 
229   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
230                         lldb_private::ThreadPlan *new_plan);
231 
232   lldb::ExecutionContextRefSP m_opaque_sp;
233 
234   lldb_private::Thread *operator->();
235 
236   lldb_private::Thread *get();
237 };
238 
239 } // namespace lldb
240 
241 #endif // LLDB_API_SBTHREAD_H
242