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
10namespace lldb {
11
12%feature("docstring",
13"Represents a thread of execution. SBProcess contains SBThread(s).
14
15SBThreads 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
21SBThread 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:
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