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 StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
97 
98   void StepInto(const char *target_name,
99                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
100 
101   void StepInto(const char *target_name, uint32_t end_line, SBError &error,
102                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
103 
104   void StepOut();
105 
106   void StepOutOfFrame(lldb::SBFrame &frame);
107 
108   void StepInstruction(bool step_over);
109 
110   SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec,
111                         uint32_t line);
112 
113   SBError StepUsingScriptedThreadPlan(const char *script_class_name);
114 
115   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
116                                       bool resume_immediately);
117 
118   SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line);
119 
120   void RunToAddress(lldb::addr_t addr);
121 
122   SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value);
123 
124   SBError UnwindInnermostExpression();
125 
126   //--------------------------------------------------------------------------
127   /// LLDB currently supports process centric debugging which means when any
128   /// thread in a process stops, all other threads are stopped. The Suspend()
129   /// call here tells our process to suspend a thread and not let it run when
130   /// the other threads in a process are allowed to run. So when
131   /// SBProcess::Continue() is called, any threads that aren't suspended will
132   /// be allowed to run. If any of the SBThread functions for stepping are
133   /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
134   /// thread will not be allowed to run and these functions will simply return.
135   ///
136   /// Eventually we plan to add support for thread centric debugging where
137   /// each thread is controlled individually and each thread would broadcast
138   /// its state, but we haven't implemented this yet.
139   ///
140   /// Likewise the SBThread::Resume() call will again allow the thread to run
141   /// when the process is continued.
142   ///
143   /// Suspend() and Resume() functions are not currently reference counted, if
144   /// anyone has the need for them to be reference counted, please let us
145   /// know.
146   //--------------------------------------------------------------------------
147   bool Suspend();
148 
149   bool Resume();
150 
151   bool IsSuspended();
152 
153   bool IsStopped();
154 
155   uint32_t GetNumFrames();
156 
157   lldb::SBFrame GetFrameAtIndex(uint32_t idx);
158 
159   lldb::SBFrame GetSelectedFrame();
160 
161   lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
162 
163   static bool EventIsThreadEvent(const SBEvent &event);
164 
165   static SBFrame GetStackFrameFromEvent(const SBEvent &event);
166 
167   static SBThread GetThreadFromEvent(const SBEvent &event);
168 
169   lldb::SBProcess GetProcess();
170 
171   const lldb::SBThread &operator=(const lldb::SBThread &rhs);
172 
173   bool operator==(const lldb::SBThread &rhs) const;
174 
175   bool operator!=(const lldb::SBThread &rhs) const;
176 
177   bool GetDescription(lldb::SBStream &description) const;
178 
179   bool GetDescription(lldb::SBStream &description, bool stop_format) const;
180 
181   bool GetStatus(lldb::SBStream &status) const;
182 
183   SBThread GetExtendedBacktraceThread(const char *type);
184 
185   uint32_t GetExtendedBacktraceOriginatingIndexID();
186 
187   bool SafeToCallFunctions();
188 
189 #ifndef SWIG
190   lldb_private::Thread *operator->();
191 
192   lldb_private::Thread *get();
193 
194 #endif
195 
196 protected:
197   friend class SBBreakpoint;
198   friend class SBBreakpointLocation;
199   friend class SBBreakpointCallbackBaton;
200   friend class SBExecutionContext;
201   friend class SBFrame;
202   friend class SBProcess;
203   friend class SBDebugger;
204   friend class SBValue;
205   friend class lldb_private::QueueImpl;
206   friend class SBQueueItem;
207 
208   void SetThread(const lldb::ThreadSP &lldb_object_sp);
209 
210 #ifndef SWIG
211   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
212                         lldb_private::ThreadPlan *new_plan);
213 #endif
214 
215 private:
216   lldb::ExecutionContextRefSP m_opaque_sp;
217 };
218 
219 } // namespace lldb
220 
221 #endif // LLDB_SBThread_h_
222