blob: 145016aecf074f0177a738841d979443069d4ad1 [file] [log] [blame]
Johnny Chen357033b2011-07-18 20:13:38 +00001//===-- 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
10namespace lldb {
11
12%feature("docstring",
13"Represents a thread of execution. SBProcess contains SBThread(s).
14
Jim Ingham18b46892012-07-13 20:18:18 +000015SBThreads can be referred to by their ID, which maps to the system specific thread
16identifier, or by IndexID. The ID may or may not be unique depending on whether the
17system reuses its thread identifiers. The IndexID is a monotonically increasing identifier
18that will always uniquely reference a particular thread, and when that thread goes
19away it will not be reused.
20
Johnny Chen357033b2011-07-18 20:13:38 +000021SBThread supports frame iteration. For example (from test/python_api/
22lldbutil/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
39See also SBProcess and SBFrame."
40) SBThread;
41class SBThread
42{
43public:
Daniel Malea54e14612013-10-03 22:21:09 +000044 //------------------------------------------------------------------
45 // Broadcaster bits.
46 //------------------------------------------------------------------
47 enum
48 {
49 eBroadcastBitStackChanged = (1 << 0),
50 eBroadcastBitThreadSuspended = (1 << 1),
51 eBroadcastBitThreadResumed = (1 << 2),
52 eBroadcastBitSelectedFrameChanged = (1 << 3),
53 eBroadcastBitThreadSelected = (1 << 4)
54 };
55
56
Johnny Chen357033b2011-07-18 20:13:38 +000057 SBThread ();
58
59 SBThread (const lldb::SBThread &thread);
60
61 ~SBThread();
Daniel Malea54e14612013-10-03 22:21:09 +000062
63 static const char *
64 GetBroadcasterClassName ();
Jim Ingham4f465cf2012-10-10 18:32:14 +000065
66 static bool
67 EventIsThreadEvent (const SBEvent &event);
68
69 static SBFrame
70 GetStackFrameFromEvent (const SBEvent &event);
71
72 static SBThread
73 GetThreadFromEvent (const SBEvent &event);
Johnny Chen357033b2011-07-18 20:13:38 +000074
75 bool
76 IsValid() const;
77
78 void
79 Clear ();
80
81 lldb::StopReason
82 GetStopReason();
83
84 %feature("docstring", "
85 /// Get the number of words associated with the stop reason.
86 /// See also GetStopReasonDataAtIndex().
87 ") GetStopReasonDataCount;
88 size_t
89 GetStopReasonDataCount();
90
91 %feature("docstring", "
92 //--------------------------------------------------------------------------
93 /// Get information associated with a stop reason.
94 ///
95 /// Breakpoint stop reasons will have data that consists of pairs of
96 /// breakpoint IDs followed by the breakpoint location IDs (they always come
97 /// in pairs).
98 ///
99 /// Stop Reason Count Data Type
100 /// ======================== ===== =========================================
101 /// eStopReasonNone 0
102 /// eStopReasonTrace 0
103 /// eStopReasonBreakpoint N duple: {breakpoint id, location id}
Johnny Chen290fa412011-12-17 02:07:52 +0000104 /// eStopReasonWatchpoint 1 watchpoint id
Johnny Chen357033b2011-07-18 20:13:38 +0000105 /// eStopReasonSignal 1 unix signal number
106 /// eStopReasonException N exception data
Greg Clayton90ba8112012-12-05 00:16:59 +0000107 /// eStopReasonExec 0
Johnny Chen357033b2011-07-18 20:13:38 +0000108 /// eStopReasonPlanComplete 0
109 //--------------------------------------------------------------------------
110 ") GetStopReasonDataAtIndex;
111 uint64_t
112 GetStopReasonDataAtIndex(uint32_t idx);
113
Johnny Chencdd7e8b2011-12-19 19:38:09 +0000114 %feature("autodoc", "
115 Pass only an (int)length and expect to get a Python string describing the
116 stop reason.
117 ") GetStopDescription;
Johnny Chen357033b2011-07-18 20:13:38 +0000118 size_t
119 GetStopDescription (char *dst, size_t dst_len);
120
Jim Ingham73ca05a2011-12-17 01:35:57 +0000121 SBValue
122 GetStopReturnValue ();
123
Johnny Chen357033b2011-07-18 20:13:38 +0000124 lldb::tid_t
125 GetThreadID () const;
126
127 uint32_t
128 GetIndexID () const;
129
130 const char *
131 GetName () const;
132
Jason Molenda8c713372013-11-05 11:00:35 +0000133 %feature("autodoc", "
134 Return the queue name associated with this thread, if any, as a str.
135 For example, with a libdispatch (aka Grand Central Dispatch) queue.
136 ") GetQueueName;
137
Johnny Chen357033b2011-07-18 20:13:38 +0000138 const char *
139 GetQueueName() const;
140
Jason Molenda8c713372013-11-05 11:00:35 +0000141 %feature("autodoc", "
142 Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
143 For example, with a libdispatch (aka Grand Central Dispatch) queue.
144 ") GetQueueID;
145
Jason Molenda4fdb5862013-10-21 23:52:54 +0000146 lldb::queue_id_t
147 GetQueueID() const;
148
Johnny Chen357033b2011-07-18 20:13:38 +0000149 void
150 StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
151
152 void
153 StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
154
155 void
Jim Inghamc6276822012-12-12 19:58:40 +0000156 StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
157
158 void
Johnny Chen357033b2011-07-18 20:13:38 +0000159 StepOut ();
160
161 void
162 StepOutOfFrame (lldb::SBFrame &frame);
163
164 void
165 StepInstruction(bool step_over);
166
167 SBError
Richard Mittonf86248d2013-09-12 02:20:34 +0000168 StepOverUntil (lldb::SBFrame &frame,
169 lldb::SBFileSpec &file_spec,
Johnny Chen357033b2011-07-18 20:13:38 +0000170 uint32_t line);
171
Richard Mittonf86248d2013-09-12 02:20:34 +0000172 SBError
173 JumpToLine (lldb::SBFileSpec &file_spec, uint32_t line);
174
Johnny Chen357033b2011-07-18 20:13:38 +0000175 void
176 RunToAddress (lldb::addr_t addr);
177
Jim Ingham44137582012-09-12 00:40:39 +0000178 SBError
Jim Inghamcb640dd2012-09-14 02:14:15 +0000179 ReturnFromFrame (SBFrame &frame, SBValue &return_value);
Jim Ingham44137582012-09-12 00:40:39 +0000180
Johnny Chen357033b2011-07-18 20:13:38 +0000181 %feature("docstring", "
182 //--------------------------------------------------------------------------
183 /// LLDB currently supports process centric debugging which means when any
184 /// thread in a process stops, all other threads are stopped. The Suspend()
185 /// call here tells our process to suspend a thread and not let it run when
186 /// the other threads in a process are allowed to run. So when
187 /// SBProcess::Continue() is called, any threads that aren't suspended will
188 /// be allowed to run. If any of the SBThread functions for stepping are
189 /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
190 /// thread will now be allowed to run and these funtions will simply return.
191 ///
192 /// Eventually we plan to add support for thread centric debugging where
193 /// each thread is controlled individually and each thread would broadcast
194 /// its state, but we haven't implemented this yet.
195 ///
196 /// Likewise the SBThread::Resume() call will again allow the thread to run
197 /// when the process is continued.
198 ///
199 /// Suspend() and Resume() functions are not currently reference counted, if
200 /// anyone has the need for them to be reference counted, please let us
201 /// know.
202 //--------------------------------------------------------------------------
203 ") Suspend;
204 bool
205 Suspend();
206
207 bool
208 Resume ();
209
210 bool
211 IsSuspended();
212
Andrew Kaylora75418d2013-04-15 23:33:53 +0000213 bool
214 IsStopped();
215
Johnny Chen357033b2011-07-18 20:13:38 +0000216 uint32_t
217 GetNumFrames ();
218
219 lldb::SBFrame
220 GetFrameAtIndex (uint32_t idx);
221
222 lldb::SBFrame
223 GetSelectedFrame ();
224
225 lldb::SBFrame
226 SetSelectedFrame (uint32_t frame_idx);
227
228 lldb::SBProcess
229 GetProcess ();
230
231 bool
232 GetDescription (lldb::SBStream &description) const;
Greg Clayton13d19502012-01-29 06:07:39 +0000233
Jim Ingham4f465cf2012-10-10 18:32:14 +0000234 bool
235 GetStatus (lldb::SBStream &status) const;
236
Enrico Granatac3387332013-05-03 01:29:27 +0000237 bool
238 operator == (const lldb::SBThread &rhs) const;
239
240 bool
241 operator != (const lldb::SBThread &rhs) const;
242
Jason Molenda5dd49162013-11-06 00:04:44 +0000243 %feature("autodoc","
244 Given an argument of str to specify the type of thread-origin extended
245 backtrace to retrieve, query whether the origin of this thread is
246 available. An SBThread is retured; SBThread.IsValid will return true
247 if an extended backtrace was available. The returned SBThread is not
248 a part of the SBProcess' thread list and it cannot be manipulated like
249 normal threads -- you cannot step or resume it, for instance -- it is
250 intended to used primarily for generating a backtrace. You may request
251 the returned thread's own thread origin in turn.
Jason Molenda008c45f2013-11-12 23:33:32 +0000252 ") GetExtendedBacktraceThread;
Jason Molenda5dd49162013-11-06 00:04:44 +0000253 lldb::SBThread
Jason Molenda008c45f2013-11-12 23:33:32 +0000254 GetExtendedBacktraceThread (const char *type);
Jason Molenda5dd49162013-11-06 00:04:44 +0000255
Greg Clayton13d19502012-01-29 06:07:39 +0000256 %pythoncode %{
Greg Claytonb62bb8c2012-02-03 03:22:53 +0000257 class frames_access(object):
Greg Clayton6b2bd932012-02-01 08:09:32 +0000258 '''A helper object that will lazily hand out frames for a thread when supplied an index.'''
259 def __init__(self, sbthread):
260 self.sbthread = sbthread
261
262 def __len__(self):
263 if self.sbthread:
Filipe Cabecinhas1a96ef82012-05-11 20:39:42 +0000264 return int(self.sbthread.GetNumFrames())
Greg Clayton6b2bd932012-02-01 08:09:32 +0000265 return 0
266
267 def __getitem__(self, key):
268 if type(key) is int and key < self.sbthread.GetNumFrames():
269 return self.sbthread.GetFrameAtIndex(key)
270 return None
271
Greg Claytonb62bb8c2012-02-03 03:22:53 +0000272 def get_frames_access_object(self):
273 '''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
274 return self.frames_access (self)
Greg Clayton6b2bd932012-02-01 08:09:32 +0000275
Greg Clayton24155862012-02-01 02:30:27 +0000276 def get_thread_frames(self):
Greg Claytonb62bb8c2012-02-03 03:22:53 +0000277 '''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
Greg Clayton24155862012-02-01 02:30:27 +0000278 frames = []
279 for frame in self:
280 frames.append(frame)
281 return frames
Greg Clayton6b2bd932012-02-01 08:09:32 +0000282
Greg Clayton13d19502012-01-29 06:07:39 +0000283 __swig_getmethods__["id"] = GetThreadID
Greg Clayton5ef31a92012-06-29 22:00:42 +0000284 if _newclass: id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000285
286 __swig_getmethods__["idx"] = GetIndexID
Greg Clayton5ef31a92012-06-29 22:00:42 +0000287 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000288
289 __swig_getmethods__["return_value"] = GetStopReturnValue
Greg Clayton5ef31a92012-06-29 22:00:42 +0000290 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000291
292 __swig_getmethods__["process"] = GetProcess
Greg Clayton5ef31a92012-06-29 22:00:42 +0000293 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000294
295 __swig_getmethods__["num_frames"] = GetNumFrames
Greg Clayton5ef31a92012-06-29 22:00:42 +0000296 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000297
Greg Clayton24155862012-02-01 02:30:27 +0000298 __swig_getmethods__["frames"] = get_thread_frames
Greg Clayton5ef31a92012-06-29 22:00:42 +0000299 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.''')
Greg Clayton24155862012-02-01 02:30:27 +0000300
Greg Claytonb62bb8c2012-02-03 03:22:53 +0000301 __swig_getmethods__["frame"] = get_frames_access_object
Greg Clayton5ef31a92012-06-29 22:00:42 +0000302 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]").''')
Greg Clayton6b2bd932012-02-01 08:09:32 +0000303
Greg Clayton13d19502012-01-29 06:07:39 +0000304 __swig_getmethods__["name"] = GetName
Greg Clayton5ef31a92012-06-29 22:00:42 +0000305 if _newclass: name = property(GetName, None, doc='''A read only property that returns the name of this thread as a string.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000306
307 __swig_getmethods__["queue"] = GetQueueName
Greg Clayton5ef31a92012-06-29 22:00:42 +0000308 if _newclass: queue = property(GetQueueName, None, doc='''A read only property that returns the dispatch queue name of this thread as a string.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000309
Jason Molenda4fdb5862013-10-21 23:52:54 +0000310 __swig_getmethods__["queue_id"] = GetQueueID
Jason Molenda5e873db2013-10-22 01:37:18 +0000311 if _newclass: queue_id = property(GetQueueID, None, doc='''A read only property that returns the dispatch queue id of this thread as an integer.''')
Jason Molenda4fdb5862013-10-21 23:52:54 +0000312
Greg Clayton13d19502012-01-29 06:07:39 +0000313 __swig_getmethods__["stop_reason"] = GetStopReason
Greg Clayton5ef31a92012-06-29 22:00:42 +0000314 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000315
316 __swig_getmethods__["is_suspended"] = IsSuspended
Greg Clayton5ef31a92012-06-29 22:00:42 +0000317 if _newclass: is_suspended = property(IsSuspended, None, doc='''A read only property that returns a boolean value that indicates if this thread is suspended.''')
Andrew Kaylora75418d2013-04-15 23:33:53 +0000318
319 __swig_getmethods__["is_stopped"] = IsStopped
320 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.''')
Greg Clayton13d19502012-01-29 06:07:39 +0000321 %}
322
Johnny Chen357033b2011-07-18 20:13:38 +0000323};
324
325} // namespace lldb