1 //===-- SWIG Interface for SBThread -----------------------------*- 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 namespace lldb {
11 
12 %feature("docstring",
13 "Represents a thread of execution. SBProcess contains SBThread(s).
14 
15 SBThreads can be referred to by their ID, which maps to the system specific thread
16 identifier, or by IndexID.  The ID may or may not be unique depending on whether the
17 system reuses its thread identifiers.  The IndexID is a monotonically increasing identifier
18 that will always uniquely reference a particular thread, and when that thread goes
19 away it will not be reused.
20 
21 SBThread supports frame iteration. For example (from test/python_api/
22 lldbutil/iter/TestLLDBIterator.py),
23 
24         from lldbutil import print_stacktrace
25         stopped_due_to_breakpoint = False
26         for thread in process:
27             if self.TraceOn():
28                 print_stacktrace(thread)
29             ID = thread.GetThreadID()
30             if thread.GetStopReason() == lldb.eStopReasonBreakpoint:
31                 stopped_due_to_breakpoint = True
32             for frame in thread:
33                 self.assertTrue(frame.GetThread().GetThreadID() == ID)
34                 if self.TraceOn():
35                     print frame
36 
37         self.assertTrue(stopped_due_to_breakpoint)
38 
39 See also SBProcess and SBFrame."
40 ) SBThread;
41 class SBThread
42 {
43 public:
44     SBThread ();
45 
46     SBThread (const lldb::SBThread &thread);
47 
48    ~SBThread();
49 
50     static bool
51     EventIsThreadEvent (const SBEvent &event);
52 
53     static SBFrame
54     GetStackFrameFromEvent (const SBEvent &event);
55 
56     static SBThread
57     GetThreadFromEvent (const SBEvent &event);
58 
59     bool
60     IsValid() const;
61 
62     void
63     Clear ();
64 
65     lldb::StopReason
66     GetStopReason();
67 
68     %feature("docstring", "
69     /// Get the number of words associated with the stop reason.
70     /// See also GetStopReasonDataAtIndex().
71     ") GetStopReasonDataCount;
72     size_t
73     GetStopReasonDataCount();
74 
75     %feature("docstring", "
76     //--------------------------------------------------------------------------
77     /// Get information associated with a stop reason.
78     ///
79     /// Breakpoint stop reasons will have data that consists of pairs of
80     /// breakpoint IDs followed by the breakpoint location IDs (they always come
81     /// in pairs).
82     ///
83     /// Stop Reason              Count Data Type
84     /// ======================== ===== =========================================
85     /// eStopReasonNone          0
86     /// eStopReasonTrace         0
87     /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
88     /// eStopReasonWatchpoint    1     watchpoint id
89     /// eStopReasonSignal        1     unix signal number
90     /// eStopReasonException     N     exception data
91     /// eStopReasonExec          0
92     /// eStopReasonPlanComplete  0
93     //--------------------------------------------------------------------------
94     ") GetStopReasonDataAtIndex;
95     uint64_t
96     GetStopReasonDataAtIndex(uint32_t idx);
97 
98     %feature("autodoc", "
99     Pass only an (int)length and expect to get a Python string describing the
100     stop reason.
101     ") GetStopDescription;
102     size_t
103     GetStopDescription (char *dst, size_t dst_len);
104 
105     SBValue
106     GetStopReturnValue ();
107 
108     lldb::tid_t
109     GetThreadID () const;
110 
111     uint32_t
112     GetIndexID () const;
113 
114     const char *
115     GetName () const;
116 
117     const char *
118     GetQueueName() const;
119 
120     void
121     StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
122 
123     void
124     StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
125 
126     void
127     StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
128 
129     void
130     StepOut ();
131 
132     void
133     StepOutOfFrame (lldb::SBFrame &frame);
134 
135     void
136     StepInstruction(bool step_over);
137 
138     SBError
139     StepOverUntil (lldb::SBFrame &frame,
140                    lldb::SBFileSpec &file_spec,
141                    uint32_t line);
142 
143     void
144     RunToAddress (lldb::addr_t addr);
145 
146     SBError
147     ReturnFromFrame (SBFrame &frame, SBValue &return_value);
148 
149     %feature("docstring", "
150     //--------------------------------------------------------------------------
151     /// LLDB currently supports process centric debugging which means when any
152     /// thread in a process stops, all other threads are stopped. The Suspend()
153     /// call here tells our process to suspend a thread and not let it run when
154     /// the other threads in a process are allowed to run. So when
155     /// SBProcess::Continue() is called, any threads that aren't suspended will
156     /// be allowed to run. If any of the SBThread functions for stepping are
157     /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
158     /// thread will now be allowed to run and these funtions will simply return.
159     ///
160     /// Eventually we plan to add support for thread centric debugging where
161     /// each thread is controlled individually and each thread would broadcast
162     /// its state, but we haven't implemented this yet.
163     ///
164     /// Likewise the SBThread::Resume() call will again allow the thread to run
165     /// when the process is continued.
166     ///
167     /// Suspend() and Resume() functions are not currently reference counted, if
168     /// anyone has the need for them to be reference counted, please let us
169     /// know.
170     //--------------------------------------------------------------------------
171     ") Suspend;
172     bool
173     Suspend();
174 
175     bool
176     Resume ();
177 
178     bool
179     IsSuspended();
180 
181     bool
182     IsStopped();
183 
184     uint32_t
185     GetNumFrames ();
186 
187     lldb::SBFrame
188     GetFrameAtIndex (uint32_t idx);
189 
190     lldb::SBFrame
191     GetSelectedFrame ();
192 
193     lldb::SBFrame
194     SetSelectedFrame (uint32_t frame_idx);
195 
196     lldb::SBProcess
197     GetProcess ();
198 
199     bool
200     GetDescription (lldb::SBStream &description) const;
201 
202     bool
203     GetStatus (lldb::SBStream &status) const;
204 
205     bool
206     operator == (const lldb::SBThread &rhs) const;
207 
208     bool
209     operator != (const lldb::SBThread &rhs) const;
210 
211     %pythoncode %{
212         class frames_access(object):
213             '''A helper object that will lazily hand out frames for a thread when supplied an index.'''
214             def __init__(self, sbthread):
215                 self.sbthread = sbthread
216 
217             def __len__(self):
218                 if self.sbthread:
219                     return int(self.sbthread.GetNumFrames())
220                 return 0
221 
222             def __getitem__(self, key):
223                 if type(key) is int and key < self.sbthread.GetNumFrames():
224                     return self.sbthread.GetFrameAtIndex(key)
225                 return None
226 
227         def get_frames_access_object(self):
228             '''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
229             return self.frames_access (self)
230 
231         def get_thread_frames(self):
232             '''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
233             frames = []
234             for frame in self:
235                 frames.append(frame)
236             return frames
237 
238         __swig_getmethods__["id"] = GetThreadID
239         if _newclass: id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')
240 
241         __swig_getmethods__["idx"] = GetIndexID
242         if _newclass: idx = property(GetIndexID, None, doc='''A read only property that returns the thread index ID as an integer. Thread index ID values start at 1 and increment as threads come and go and can be used to uniquely identify threads.''')
243 
244         __swig_getmethods__["return_value"] = GetStopReturnValue
245         if _newclass: return_value = property(GetStopReturnValue, None, doc='''A read only property that returns an lldb object that represents the return value from the last stop (lldb.SBValue) if we just stopped due to stepping out of a function.''')
246 
247         __swig_getmethods__["process"] = GetProcess
248         if _newclass: process = property(GetProcess, None, doc='''A read only property that returns an lldb object that represents the process (lldb.SBProcess) that owns this thread.''')
249 
250         __swig_getmethods__["num_frames"] = GetNumFrames
251         if _newclass: num_frames = property(GetNumFrames, None, doc='''A read only property that returns the number of stack frames in this thread as an integer.''')
252 
253         __swig_getmethods__["frames"] = get_thread_frames
254         if _newclass: frames = property(get_thread_frames, None, doc='''A read only property that returns a list() of lldb.SBFrame objects for all frames in this thread.''')
255 
256         __swig_getmethods__["frame"] = get_frames_access_object
257         if _newclass: frame = property(get_frames_access_object, None, doc='''A read only property that returns an object that can be used to access frames as an array ("frame_12 = lldb.thread.frame[12]").''')
258 
259         __swig_getmethods__["name"] = GetName
260         if _newclass: name = property(GetName, None, doc='''A read only property that returns the name of this thread as a string.''')
261 
262         __swig_getmethods__["queue"] = GetQueueName
263         if _newclass: queue = property(GetQueueName, None, doc='''A read only property that returns the dispatch queue name of this thread as a string.''')
264 
265         __swig_getmethods__["stop_reason"] = GetStopReason
266         if _newclass: stop_reason = property(GetStopReason, None, doc='''A read only property that returns an lldb enumeration value (see enumerations that start with "lldb.eStopReason") that represents the reason this thread stopped.''')
267 
268         __swig_getmethods__["is_suspended"] = IsSuspended
269         if _newclass: is_suspended = property(IsSuspended, None, doc='''A read only property that returns a boolean value that indicates if this thread is suspended.''')
270 
271         __swig_getmethods__["is_stopped"] = IsStopped
272         if _newclass: is_stopped = property(IsStopped, None, doc='''A read only property that returns a boolean value that indicates if this thread is stopped but not exited.''')
273     %}
274 
275 };
276 
277 } // namespace lldb
278