229 lines · plain
1%feature("docstring",2"Represents a thread of execution. :py:class:`SBProcess` contains SBThread(s).3 4SBThreads can be referred to by their ID, which maps to the system specific thread5identifier, or by IndexID. The ID may or may not be unique depending on whether the6system reuses its thread identifiers. The IndexID is a monotonically increasing identifier7that will always uniquely reference a particular thread, and when that thread goes8away it will not be reused.9 10SBThread supports frame iteration. For example (from test/python_api/11lldbutil/iter/TestLLDBIterator.py), ::12 13 from lldbutil import print_stacktrace14 stopped_due_to_breakpoint = False15 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 = True21 for frame in thread:22 self.assertTrue(frame.GetThread().GetThreadID() == ID)23 if self.TraceOn():24 print frame25 26 self.assertTrue(stopped_due_to_breakpoint)27 28See also :py:class:`SBFrame` ."29) lldb::SBThread;30 31%feature("docstring", "32 Get the number of words associated with the stop reason.33 See also GetStopReasonDataAtIndex()."34) lldb::SBThread::GetStopReasonDataCount;35 36%feature("docstring", "37 Get information associated with a stop reason.38 39 Breakpoint stop reasons will have data that consists of pairs of40 breakpoint IDs followed by the breakpoint location IDs (they always come41 in pairs).42 43 Stop Reason Count Data Type44 ======================== ===== =========================================45 eStopReasonNone 046 eStopReasonTrace 047 eStopReasonBreakpoint N duple: {breakpoint id, location id}48 eStopReasonWatchpoint 1 watchpoint id49 eStopReasonSignal 1 unix signal number50 eStopReasonException N exception data51 eStopReasonExec 052 eStopReasonFork 1 pid of the child process53 eStopReasonVFork 1 pid of the child process54 eStopReasonVForkDone 055 eStopReasonPlanComplete 0"56) lldb::SBThread::GetStopReasonDataAtIndex;57 58%feature("docstring", "59 Collects a thread's stop reason extended information dictionary and prints it60 into the SBStream in a JSON format. The format of this JSON dictionary depends61 on the stop reason and is currently used only for instrumentation plugins."62) lldb::SBThread::GetStopReasonExtendedInfoAsJSON;63 64%feature("docstring", "65 Returns a collection of historical stack traces that are significant to the66 current stop reason. Used by ThreadSanitizer, where we provide various stack67 traces that were involved in a data race or other type of detected issue."68) lldb::SBThread::GetStopReasonExtendedBacktraces;69 70%feature("docstring", "71 Pass only an (int)length and expect to get a Python string describing the72 stop reason."73) lldb::SBThread::GetStopDescription;74 75%feature("docstring", "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's78 lifetime in this process and will not be reused by another thread during this79 process lifetime. On Mac OS X systems, this is a system-wide unique thread80 identifier; this identifier is also used by other tools like sample which helps81 to associate data from those tools with lldb. See related GetIndexID."82) lldb::SBThread::GetThreadID;83 84%feature("docstring", "85 Return the index number for this SBThread. The index number is the same thing86 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 be89 reused for a different thread later in a process - thread 1 will always be90 associated with the same thread. See related GetThreadID.91 This method returns a uint32_t index number, takes no arguments."92) lldb::SBThread::GetIndexID;93 94%feature("docstring", "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."97) lldb::SBThread::GetQueueName;98 99%feature("docstring", "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."102) lldb::SBThread::GetQueueID;103 104%feature("docstring", "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 path107 argument to descend into the dictionary to an item of interest, and prints108 it into the SBStream in a natural format. Return bool is to indicate if109 anything was printed into the stream (true) or not (false)."110) lldb::SBThread::GetInfoItemByPathAsString;111 112%feature("docstring", "113 Return the SBQueue for this thread. If this thread is not currently associated114 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 QueueID116 and QueueName, but not provide an SBQueue. Those individual attributes may have117 been saved for the HistoryThread without enough information to reconstitute the118 entire SBQueue at that time.119 This method takes no arguments, returns an SBQueue."120) lldb::SBThread::GetQueue;121 122%feature("docstring",123 "Do a source level single step over in the currently selected thread."124) lldb::SBThread::StepOver;125 126%feature("docstring", "127 Step the current thread from the current source line to the line given by end_line, stopping if128 the thread steps into the function given by target_name. If target_name is None, then stepping will stop129 in any of the places we would normally stop."130) lldb::SBThread::StepInto;131 132%feature("docstring",133 "Step out of the currently selected thread."134) lldb::SBThread::StepOut;135 136%feature("docstring",137 "Step out of the specified frame."138) lldb::SBThread::StepOutOfFrame;139 140%feature("docstring",141 "Do an instruction level single step in the currently selected thread."142) lldb::SBThread::StepInstruction;143 144%feature("docstring", "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 contains147 a valid SBValue, that will be set as the return value from frame. Note, at148 present only scalar return values are supported."149) lldb::SBThread::ReturnFromFrame;150 151%feature("docstring", "152 Unwind the stack frames from the innermost expression evaluation.153 This API is equivalent to 'thread return -x'."154) lldb::SBThread::UnwindInnermostExpression;155 156%feature("docstring", "157 LLDB currently supports process centric debugging which means when any158 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 when160 the other threads in a process are allowed to run. So when161 SBProcess::Continue() is called, any threads that aren't suspended will162 be allowed to run. If any of the SBThread functions for stepping are163 called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the164 thread will now be allowed to run and these functions will simply return.165 166 Eventually we plan to add support for thread centric debugging where167 each thread is controlled individually and each thread would broadcast168 its state, but we haven't implemented this yet.169 170 Likewise the SBThread::Resume() call will again allow the thread to run171 when the process is continued.172 173 Suspend() and Resume() functions are not currently reference counted, if174 anyone has the need for them to be reference counted, please let us175 know."176) lldb::SBThread::Suspend;177 178%feature("docstring", "179 Get the description strings for this thread that match what the180 lldb driver will present, using the thread-format (stop_format==false)181 or thread-stop-format (stop_format = true)."182) lldb::SBThread::GetDescription;183 184%feature("docstring","185 Given an argument of str to specify the type of thread-origin extended186 backtrace to retrieve, query whether the origin of this thread is187 available. An SBThread is retured; SBThread.IsValid will return true188 if an extended backtrace was available. The returned SBThread is not189 a part of the SBProcess' thread list and it cannot be manipulated like190 normal threads -- you cannot step or resume it, for instance -- it is191 intended to used primarily for generating a backtrace. You may request192 the returned thread's own thread origin in turn."193) lldb::SBThread::GetExtendedBacktraceThread;194 195%feature("docstring","196 If this SBThread is an ExtendedBacktrace thread, get the IndexID of the197 original thread that this ExtendedBacktrace thread represents, if198 available. The thread that was running this backtrace in the past may199 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."202) lldb::SBThread::GetExtendedBacktraceOriginatingIndexID;203 204%feature("docstring","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 SBValue207 representing the NSException object at the throw site or that's currently208 being processes."209) lldb::SBThread::GetCurrentException;210 211%feature("docstring","212 Returns a historical (fake) SBThread representing the stack trace of an213 exception, if there is one for the thread. Currently, this works for Obj-C214 code, and can retrieve the throw-site backtrace of an NSException object215 even when the program is no longer at the throw site."216) lldb::SBThread::GetCurrentExceptionBacktrace;217 218%feature("docstring","219 lldb may be able to detect that function calls should not be executed220 on a given thread at a particular point in time. It is recommended that221 this is checked before performing an inferior function call on a given222 thread."223) lldb::SBThread::SafeToCallFunctions;224 225%feature("docstring","226 Returns a SBValue object representing the siginfo for the current signal.227 "228) lldb::SBThread::GetSiginfo;229