| blob | 76822e49c6384185df972e7a1ad4fa87d58f0ee2 |
2 "Represents a thread of execution. :py:class:`SBProcess` contains SBThread(s).
4 SBThreads can be referred to by their ID, which maps to the system specific thread
5 identifier, or by IndexID. The ID may or may not be unique depending on whether the
6 system reuses its thread identifiers. The IndexID is a monotonically increasing identifier
7 that will always uniquely reference a particular thread, and when that thread goes
8 away it will not be reused.
10 SBThread supports frame iteration. For example (from test/python_api/
11 lldbutil/iter/TestLLDBIterator.py), ::
13 from lldbutil import print_stacktrace
14 stopped_due_to_breakpoint = False
15 for thread in process:
16 if self.TraceOn():
17 print_stacktrace(thread)
18 ID = thread.GetThreadID()
19 if thread.GetStopReason() == lldb.eStopReasonBreakpoint:
20 stopped_due_to_breakpoint = True
21 for frame in thread:
22 self.assertTrue(frame.GetThread().GetThreadID() == ID)
23 if self.TraceOn():
24 print frame
26 self.assertTrue(stopped_due_to_breakpoint)
28 See also :py:class:`SBFrame` ."
32 Get the number of words associated with the stop reason.
33 See also GetStopReasonDataAtIndex()."
37 Get information associated with a stop reason.
39 Breakpoint stop reasons will have data that consists of pairs of
40 breakpoint IDs followed by the breakpoint location IDs (they always come
41 in pairs).
43 Stop Reason Count Data Type
44 ======================== ===== =========================================
45 eStopReasonNone 0
46 eStopReasonTrace 0
47 eStopReasonBreakpoint N duple: {breakpoint id, location id}
48 eStopReasonWatchpoint 1 watchpoint id
49 eStopReasonSignal 1 unix signal number
50 eStopReasonException N exception data
51 eStopReasonExec 0
52 eStopReasonFork 1 pid of the child process
53 eStopReasonVFork 1 pid of the child process
54 eStopReasonVForkDone 0
55 eStopReasonPlanComplete 0"
59 Collects a thread's stop reason extended information dictionary and prints it
60 into the SBStream in a JSON format. The format of this JSON dictionary depends
61 on the stop reason and is currently used only for instrumentation plugins."
65 Returns a collection of historical stack traces that are significant to the
66 current stop reason. Used by ThreadSanitizer, where we provide various stack
67 traces that were involved in a data race or other type of detected issue."
71 Pass only an (int)length and expect to get a Python string describing the
72 stop reason."
76 Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type)
77 for the current SBThread that will remain constant throughout the thread's
78 lifetime in this process and will not be reused by another thread during this
79 process lifetime. On Mac OS X systems, this is a system-wide unique thread
80 identifier; this identifier is also used by other tools like sample which helps
81 to associate data from those tools with lldb. See related GetIndexID."
85 Return the index number for this SBThread. The index number is the same thing
86 that a user gives as an argument to 'thread select' in the command line lldb.
87 These numbers start at 1 (for the first thread lldb sees in a debug session)
88 and increments up throughout the process lifetime. An index number will not be
89 reused for a different thread later in a process - thread 1 will always be
90 associated with the same thread. See related GetThreadID.
91 This method returns a uint32_t index number, takes no arguments."
95 Return the queue name associated with this thread, if any, as a str.
96 For example, with a libdispatch (aka Grand Central Dispatch) queue."
100 Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
101 For example, with a libdispatch (aka Grand Central Dispatch) queue."
105 Takes a path string and a SBStream reference as parameters, returns a bool.
106 Collects the thread's 'info' dictionary from the remote system, uses the path
107 argument to descend into the dictionary to an item of interest, and prints
108 it into the SBStream in a natural format. Return bool is to indicate if
109 anything was printed into the stream (true) or not (false)."
113 Return the SBQueue for this thread. If this thread is not currently associated
114 with a libdispatch queue, the SBQueue object's IsValid() method will return false.
115 If this SBThread is actually a HistoryThread, we may be able to provide QueueID
116 and QueueName, but not provide an SBQueue. Those individual attributes may have
117 been saved for the HistoryThread without enough information to reconstitute the
118 entire SBQueue at that time.
119 This method takes no arguments, returns an SBQueue."
123 "Do a source level single step over in the currently selected thread."
127 Step the current thread from the current source line to the line given by end_line, stopping if
128 the thread steps into the function given by target_name. If target_name is None, then stepping will stop
129 in any of the places we would normally stop."
133 "Step out of the currently selected thread."
137 "Step out of the specified frame."
141 "Do an instruction level single step in the currently selected thread."
145 Force a return from the frame passed in (and any frames younger than it)
146 without executing any more code in those frames. If return_value contains
147 a valid SBValue, that will be set as the return value from frame. Note, at
148 present only scalar return values are supported."
152 Unwind the stack frames from the innermost expression evaluation.
153 This API is equivalent to 'thread return -x'."
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, RunToAddres), the
164 thread will now be allowed to run and these functions will simply return.
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.
170 Likewise the SBThread::Resume() call will again allow the thread to run
171 when the process is continued.
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."
179 Get the description strings for this thread that match what the
180 lldb driver will present, using the thread-format (stop_format==false)
181 or thread-stop-format (stop_format = true)."
185 Given an argument of str to specify the type of thread-origin extended
186 backtrace to retrieve, query whether the origin of this thread is
187 available. An SBThread is retured; SBThread.IsValid will return true
188 if an extended backtrace was available. The returned SBThread is not
189 a part of the SBProcess' thread list and it cannot be manipulated like
190 normal threads -- you cannot step or resume it, for instance -- it is
191 intended to used primarily for generating a backtrace. You may request
192 the returned thread's own thread origin in turn."
196 If this SBThread is an ExtendedBacktrace thread, get the IndexID of the
197 original thread that this ExtendedBacktrace thread represents, if
198 available. The thread that was running this backtrace in the past may
199 not have been registered with lldb's thread index (if it was created,
200 did its work, and was destroyed without lldb ever stopping execution).
201 In that case, this ExtendedBacktrace thread's IndexID will be returned."
205 Returns an SBValue object represeting the current exception for the thread,
206 if there is any. Currently, this works for Obj-C code and returns an SBValue
207 representing the NSException object at the throw site or that's currently
208 being processes."
212 Returns a historical (fake) SBThread representing the stack trace of an
213 exception, if there is one for the thread. Currently, this works for Obj-C
214 code, and can retrieve the throw-site backtrace of an NSException object
215 even when the program is no longer at the throw site."
219 lldb may be able to detect that function calls should not be executed
220 on a given thread at a particular point in time. It is recommended that
221 this is checked before performing an inferior function call on a given
222 thread."
226 Returns a SBValue object representing the siginfo for the current signal.
227 "