1 //===-- SBThread.h ----------------------------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLDB_SBThread_h_
11 #define LLDB_SBThread_h_
12 
13 #include "lldb/API/SBDefines.h"
14 
15 #include <stdio.h>
16 
17 namespace lldb {
18 
19 class SBFrame;
20 
21 class LLDB_API SBThread {
22 public:
23   enum {
24     eBroadcastBitStackChanged = (1 << 0),
25     eBroadcastBitThreadSuspended = (1 << 1),
26     eBroadcastBitThreadResumed = (1 << 2),
27     eBroadcastBitSelectedFrameChanged = (1 << 3),
28     eBroadcastBitThreadSelected = (1 << 4)
29   };
30 
31   static const char *GetBroadcasterClassName();
32 
33   SBThread();
34 
35   SBThread(const lldb::SBThread &thread);
36 
37   SBThread(const lldb::ThreadSP &lldb_object_sp);
38 
39   ~SBThread();
40 
41   lldb::SBQueue GetQueue() const;
42 
43   bool IsValid() const;
44 
45   void Clear();
46 
47   lldb::StopReason GetStopReason();
48 
49   /// Get the number of words associated with the stop reason.
50   /// See also GetStopReasonDataAtIndex().
51   size_t GetStopReasonDataCount();
52 
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   //--------------------------------------------------------------------------
71   uint64_t GetStopReasonDataAtIndex(uint32_t idx);
72 
73   bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream);
74 
75   SBThreadCollection
76   GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type);
77 
78   size_t GetStopDescription(char *dst, size_t dst_len);
79 
80   SBValue GetStopReturnValue();
81 
82   lldb::tid_t GetThreadID() const;
83 
84   uint32_t GetIndexID() const;
85 
86   const char *GetName() const;
87 
88   const char *GetQueueName() const;
89 
90   lldb::queue_id_t GetQueueID() const;
91 
92   bool GetInfoItemByPathAsString(const char *path, SBStream &strm);
93 
94   void StepOver(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
95 
96   void StepOver(lldb::RunMode stop_other_threads, SBError &error);
97 
98   void StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
99 
100   void StepInto(const char *target_name,
101                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
102 
103   void StepInto(const char *target_name, uint32_t end_line, SBError &error,
104                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
105 
106   void StepOut();
107 
108   void StepOut(SBError &error);
109 
110   void StepOutOfFrame(SBFrame &frame);
111 
112   void StepOutOfFrame(SBFrame &frame, SBError &error);
113 
114   void StepInstruction(bool step_over);
115 
116   void StepInstruction(bool step_over, SBError &error);
117 
118   SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec,
119                         uint32_t line);
120 
121   SBError StepUsingScriptedThreadPlan(const char *script_class_name);
122 
123   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
124                                       bool resume_immediately);
125 
126   SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line);
127 
128   void RunToAddress(lldb::addr_t addr);
129 
130   void RunToAddress(lldb::addr_t addr, SBError &error);
131 
132   SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value);
133 
134   SBError UnwindInnermostExpression();
135 
136   //--------------------------------------------------------------------------
137   /// LLDB currently supports process centric debugging which means when any
138   /// thread in a process stops, all other threads are stopped. The Suspend()
139   /// call here tells our process to suspend a thread and not let it run when
140   /// the other threads in a process are allowed to run. So when
141   /// SBProcess::Continue() is called, any threads that aren't suspended will
142   /// be allowed to run. If any of the SBThread functions for stepping are
143   /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
144   /// thread will not be allowed to run and these functions will simply return.
145   ///
146   /// Eventually we plan to add support for thread centric debugging where
147   /// each thread is controlled individually and each thread would broadcast
148   /// its state, but we haven't implemented this yet.
149   ///
150   /// Likewise the SBThread::Resume() call will again allow the thread to run
151   /// when the process is continued.
152   ///
153   /// Suspend() and Resume() functions are not currently reference counted, if
154   /// anyone has the need for them to be reference counted, please let us
155   /// know.
156   //--------------------------------------------------------------------------
157   bool Suspend();
158 
159   bool Suspend(SBError &error);
160 
161   bool Resume();
162 
163   bool Resume(SBError &error);
164 
165   bool IsSuspended();
166 
167   bool IsStopped();
168 
169   uint32_t GetNumFrames();
170 
171   lldb::SBFrame GetFrameAtIndex(uint32_t idx);
172 
173   lldb::SBFrame GetSelectedFrame();
174 
175   lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
176 
177   static bool EventIsThreadEvent(const SBEvent &event);
178 
179   static SBFrame GetStackFrameFromEvent(const SBEvent &event);
180 
181   static SBThread GetThreadFromEvent(const SBEvent &event);
182 
183   lldb::SBProcess GetProcess();
184 
185   const lldb::SBThread &operator=(const lldb::SBThread &rhs);
186 
187   bool operator==(const lldb::SBThread &rhs) const;
188 
189   bool operator!=(const lldb::SBThread &rhs) const;
190 
191   bool GetDescription(lldb::SBStream &description) const;
192 
193   bool GetDescription(lldb::SBStream &description, bool stop_format) const;
194 
195   bool GetStatus(lldb::SBStream &status) const;
196 
197   SBThread GetExtendedBacktraceThread(const char *type);
198 
199   uint32_t GetExtendedBacktraceOriginatingIndexID();
200 
201   SBValue GetCurrentException();
202 
203   SBThread GetCurrentExceptionBacktrace();
204 
205   bool SafeToCallFunctions();
206 
207 #ifndef SWIG
208   lldb_private::Thread *operator->();
209 
210   lldb_private::Thread *get();
211 
212 #endif
213 
214 protected:
215   friend class SBBreakpoint;
216   friend class SBBreakpointLocation;
217   friend class SBBreakpointCallbackBaton;
218   friend class SBExecutionContext;
219   friend class SBFrame;
220   friend class SBProcess;
221   friend class SBDebugger;
222   friend class SBValue;
223   friend class lldb_private::QueueImpl;
224   friend class SBQueueItem;
225 
226   void SetThread(const lldb::ThreadSP &lldb_object_sp);
227 
228 #ifndef SWIG
229   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
230                         lldb_private::ThreadPlan *new_plan);
231 #endif
232 
233 private:
234   lldb::ExecutionContextRefSP m_opaque_sp;
235 };
236 
237 } // namespace lldb
238 
239 #endif // LLDB_SBThread_h_
240