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 {
23 public:
24     enum
25     {
26         eBroadcastBitStackChanged           = (1 << 0),
27         eBroadcastBitThreadSuspended        = (1 << 1),
28         eBroadcastBitThreadResumed          = (1 << 2),
29         eBroadcastBitSelectedFrameChanged   = (1 << 3),
30         eBroadcastBitThreadSelected         = (1 << 4)
31     };
32 
33     static const char *
34     GetBroadcasterClassName ();
35 
36     SBThread ();
37 
38     SBThread (const lldb::SBThread &thread);
39 
40     SBThread (const lldb::ThreadSP& lldb_object_sp);
41 
42    ~SBThread();
43 
44     lldb::SBQueue
45     GetQueue () const;
46 
47     bool
48     IsValid() const;
49 
50     void
51     Clear ();
52 
53     lldb::StopReason
54     GetStopReason();
55 
56     /// Get the number of words associated with the stop reason.
57     /// See also GetStopReasonDataAtIndex().
58     size_t
59     GetStopReasonDataCount();
60 
61     //--------------------------------------------------------------------------
62     /// Get information associated with a stop reason.
63     ///
64     /// Breakpoint stop reasons will have data that consists of pairs of
65     /// breakpoint IDs followed by the breakpoint location IDs (they always come
66     /// in pairs).
67     ///
68     /// Stop Reason              Count Data Type
69     /// ======================== ===== =========================================
70     /// eStopReasonNone          0
71     /// eStopReasonTrace         0
72     /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
73     /// eStopReasonWatchpoint    1     watchpoint id
74     /// eStopReasonSignal        1     unix signal number
75     /// eStopReasonException     N     exception data
76     /// eStopReasonExec          0
77     /// eStopReasonPlanComplete  0
78     //--------------------------------------------------------------------------
79     uint64_t
80     GetStopReasonDataAtIndex(uint32_t idx);
81 
82     bool
83     GetStopReasonExtendedInfoAsJSON (lldb::SBStream &stream);
84 
85     SBThreadCollection
86     GetStopReasonExtendedBacktraces (InstrumentationRuntimeType type);
87 
88     size_t
89     GetStopDescription (char *dst, size_t dst_len);
90 
91     SBValue
92     GetStopReturnValue ();
93 
94     lldb::tid_t
95     GetThreadID () const;
96 
97     uint32_t
98     GetIndexID () const;
99 
100     const char *
101     GetName () const;
102 
103     const char *
104     GetQueueName() const;
105 
106     lldb::queue_id_t
107     GetQueueID() const;
108 
109     bool
110     GetInfoItemByPathAsString ( const char *path, SBStream &strm);
111 
112     void
113     StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
114 
115     void
116     StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
117 
118     void
119     StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
120 
121     void
122     StepInto (const char *target_name,
123               uint32_t end_line,
124               SBError &error,
125               lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
126 
127     void
128     StepOut ();
129 
130     void
131     StepOutOfFrame (lldb::SBFrame &frame);
132 
133     void
134     StepInstruction(bool step_over);
135 
136     SBError
137     StepOverUntil (lldb::SBFrame &frame,
138                    lldb::SBFileSpec &file_spec,
139                    uint32_t line);
140 
141     SBError
142     StepUsingScriptedThreadPlan (const char *script_class_name);
143 
144     SBError
145     JumpToLine (lldb::SBFileSpec &file_spec, uint32_t line);
146 
147     void
148     RunToAddress (lldb::addr_t addr);
149 
150     SBError
151     ReturnFromFrame (SBFrame &frame, SBValue &return_value);
152 
153     SBError
154     UnwindInnermostExpression();
155 
156     //--------------------------------------------------------------------------
157     /// LLDB currently supports process centric debugging which means when any
158     /// thread in a process stops, all other threads are stopped. The Suspend()
159     /// call here tells our process to suspend a thread and not let it run when
160     /// the other threads in a process are allowed to run. So when
161     /// SBProcess::Continue() is called, any threads that aren't suspended will
162     /// be allowed to run. If any of the SBThread functions for stepping are
163     /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
164     /// thread will not be allowed to run and these functions will simply return.
165     ///
166     /// Eventually we plan to add support for thread centric debugging where
167     /// each thread is controlled individually and each thread would broadcast
168     /// its state, but we haven't implemented this yet.
169     ///
170     /// Likewise the SBThread::Resume() call will again allow the thread to run
171     /// when the process is continued.
172     ///
173     /// Suspend() and Resume() functions are not currently reference counted, if
174     /// anyone has the need for them to be reference counted, please let us
175     /// know.
176     //--------------------------------------------------------------------------
177     bool
178     Suspend();
179 
180     bool
181     Resume ();
182 
183     bool
184     IsSuspended();
185 
186     bool
187     IsStopped();
188 
189     uint32_t
190     GetNumFrames ();
191 
192     lldb::SBFrame
193     GetFrameAtIndex (uint32_t idx);
194 
195     lldb::SBFrame
196     GetSelectedFrame ();
197 
198     lldb::SBFrame
199     SetSelectedFrame (uint32_t frame_idx);
200 
201     static bool
202     EventIsThreadEvent (const SBEvent &event);
203 
204     static SBFrame
205     GetStackFrameFromEvent (const SBEvent &event);
206 
207     static SBThread
208     GetThreadFromEvent (const SBEvent &event);
209 
210     lldb::SBProcess
211     GetProcess ();
212 
213     const lldb::SBThread &
214     operator = (const lldb::SBThread &rhs);
215 
216     bool
217     operator == (const lldb::SBThread &rhs) const;
218 
219     bool
220     operator != (const lldb::SBThread &rhs) const;
221 
222     bool
223     GetDescription (lldb::SBStream &description) const;
224 
225     bool
226     GetStatus (lldb::SBStream &status) const;
227 
228     SBThread
229     GetExtendedBacktraceThread (const char *type);
230 
231     uint32_t
232     GetExtendedBacktraceOriginatingIndexID ();
233 
234     bool
235     SafeToCallFunctions ();
236 
237 #ifndef SWIG
238     lldb_private::Thread *
239     operator->();
240 
241     lldb_private::Thread *
242     get();
243 
244 #endif
245 
246 protected:
247     friend class SBBreakpoint;
248     friend class SBBreakpointLocation;
249     friend class SBExecutionContext;
250     friend class SBFrame;
251     friend class SBProcess;
252     friend class SBDebugger;
253     friend class SBValue;
254     friend class lldb_private::QueueImpl;
255     friend class SBQueueItem;
256 
257     void
258     SetThread (const lldb::ThreadSP& lldb_object_sp);
259 
260 #ifndef SWIG
261     SBError
262     ResumeNewPlan (lldb_private::ExecutionContext &exe_ctx, lldb_private::ThreadPlan *new_plan);
263 #endif
264 
265 private:
266     lldb::ExecutionContextRefSP m_opaque_sp;
267 };
268 
269 } // namespace lldb
270 
271 #endif  // LLDB_SBThread_h_
272