1 //===-- SWIG Interface for SBThread -----------------------------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
12 "Represents a thread of execution. SBProcess contains SBThread(s).
14 SBThreads can be referred to by their ID, which maps to the system specific thread
15 identifier, or by IndexID. The ID may or may not be unique depending on whether the
16 system reuses its thread identifiers. The IndexID is a monotonically increasing identifier
17 that will always uniquely reference a particular thread, and when that thread goes
18 away it will not be reused.
20 SBThread supports frame iteration. For example (from test/python_api/
21 lldbutil/iter/TestLLDBIterator.py),
23 from lldbutil import print_stacktrace
24 stopped_due_to_breakpoint = False
25 for thread in process:
27 print_stacktrace(thread)
28 ID = thread.GetThreadID()
29 if thread.GetStopReason() == lldb.eStopReasonBreakpoint:
30 stopped_due_to_breakpoint = True
32 self.assertTrue(frame.GetThread().GetThreadID() == ID)
36 self.assertTrue(stopped_due_to_breakpoint)
38 See also SBProcess and SBFrame."
43 //------------------------------------------------------------------
45 //------------------------------------------------------------------
48 eBroadcastBitStackChanged = (1 << 0),
49 eBroadcastBitThreadSuspended = (1 << 1),
50 eBroadcastBitThreadResumed = (1 << 2),
51 eBroadcastBitSelectedFrameChanged = (1 << 3),
52 eBroadcastBitThreadSelected = (1 << 4)
58 SBThread (const lldb::SBThread &thread);
63 GetBroadcasterClassName ();
66 EventIsThreadEvent (const SBEvent &event);
69 GetStackFrameFromEvent (const SBEvent &event);
72 GetThreadFromEvent (const SBEvent &event);
77 explicit operator bool() const;
85 %feature("docstring", "
86 Get the number of words associated with the stop reason.
87 See also GetStopReasonDataAtIndex().") GetStopReasonDataCount;
89 GetStopReasonDataCount();
91 %feature("docstring", "
92 Get information associated with a stop reason.
94 Breakpoint stop reasons will have data that consists of pairs of
95 breakpoint IDs followed by the breakpoint location IDs (they always come
98 Stop Reason Count Data Type
99 ======================== ===== =========================================
102 eStopReasonBreakpoint N duple: {breakpoint id, location id}
103 eStopReasonWatchpoint 1 watchpoint id
104 eStopReasonSignal 1 unix signal number
105 eStopReasonException N exception data
107 eStopReasonPlanComplete 0") GetStopReasonDataAtIndex;
109 GetStopReasonDataAtIndex(uint32_t idx);
111 %feature("autodoc", "
112 Collects a thread's stop reason extended information dictionary and prints it
113 into the SBStream in a JSON format. The format of this JSON dictionary depends
114 on the stop reason and is currently used only for instrumentation plugins.") GetStopReasonExtendedInfoAsJSON;
116 GetStopReasonExtendedInfoAsJSON (lldb::SBStream &stream);
118 %feature("autodoc", "
119 Returns a collection of historical stack traces that are significant to the
120 current stop reason. Used by ThreadSanitizer, where we provide various stack
121 traces that were involved in a data race or other type of detected issue.") GetStopReasonExtendedBacktraces;
123 GetStopReasonExtendedBacktraces (InstrumentationRuntimeType type);
126 %feature("autodoc", "
127 Pass only an (int)length and expect to get a Python string describing the
128 stop reason.") GetStopDescription;
130 GetStopDescription (char *dst_or_null, size_t dst_len);
133 GetStopReturnValue ();
135 %feature("autodoc", "
136 Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type)
137 for the current SBThread that will remain constant throughout the thread's
138 lifetime in this process and will not be reused by another thread during this
139 process lifetime. On Mac OS X systems, this is a system-wide unique thread
140 identifier; this identifier is also used by other tools like sample which helps
141 to associate data from those tools with lldb. See related GetIndexID.")
144 GetThreadID () const;
146 %feature("autodoc", "
147 Return the index number for this SBThread. The index number is the same thing
148 that a user gives as an argument to 'thread select' in the command line lldb.
149 These numbers start at 1 (for the first thread lldb sees in a debug session)
150 and increments up throughout the process lifetime. An index number will not be
151 reused for a different thread later in a process - thread 1 will always be
152 associated with the same thread. See related GetThreadID.
153 This method returns a uint32_t index number, takes no arguments.")
161 %feature("autodoc", "
162 Return the queue name associated with this thread, if any, as a str.
163 For example, with a libdispatch (aka Grand Central Dispatch) queue.") GetQueueName;
166 GetQueueName() const;
168 %feature("autodoc", "
169 Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
170 For example, with a libdispatch (aka Grand Central Dispatch) queue.") GetQueueID;
175 %feature("docstring", "
176 Takes a path string and a SBStream reference as parameters, returns a bool.
177 Collects the thread's 'info' dictionary from the remote system, uses the path
178 argument to descend into the dictionary to an item of interest, and prints
179 it into the SBStream in a natural format. Return bool is to indicate if
180 anything was printed into the stream (true) or not (false).") GetInfoItemByPathAsString;
183 GetInfoItemByPathAsString (const char *path, lldb::SBStream &strm);
185 %feature("autodoc", "
186 Return the SBQueue for this thread. If this thread is not currently associated
187 with a libdispatch queue, the SBQueue object's IsValid() method will return false.
188 If this SBThread is actually a HistoryThread, we may be able to provide QueueID
189 and QueueName, but not provide an SBQueue. Those individual attributes may have
190 been saved for the HistoryThread without enough information to reconstitute the
191 entire SBQueue at that time.
192 This method takes no arguments, returns an SBQueue.") GetQueue;
198 StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
201 "Do a source level single step over in the currently selected thread.") StepOver;
203 StepOver (lldb::RunMode stop_other_threads, SBError &error);
206 StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
209 StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
211 %feature("autodoc", "
212 Step the current thread from the current source line to the line given by end_line, stopping if
213 the thread steps into the function given by target_name. If target_name is None, then stepping will stop
214 in any of the places we would normally stop.") StepInto;
216 StepInto (const char *target_name,
219 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
225 "Step out of the currently selected thread.") StepOut;
227 StepOut (SBError &error);
230 StepOutOfFrame (SBFrame &frame);
233 "Step out of the specified frame.") StepOutOfFrame;
235 StepOutOfFrame (SBFrame &frame, SBError &error);
238 StepInstruction(bool step_over);
241 "Do an instruction level single step in the currently selected thread.") StepInstruction;
243 StepInstruction(bool step_over, SBError &error);
246 StepOverUntil (lldb::SBFrame &frame,
247 lldb::SBFileSpec &file_spec,
251 StepUsingScriptedThreadPlan (const char *script_class_name);
254 StepUsingScriptedThreadPlan (const char *script_class_name, bool resume_immediately);
257 StepUsingScriptedThreadPlan(const char *script_class_name,
258 lldb::SBStructuredData &args_data,
259 bool resume_immediately);
262 JumpToLine (lldb::SBFileSpec &file_spec, uint32_t line);
265 RunToAddress (lldb::addr_t addr);
268 RunToAddress (lldb::addr_t addr, SBError &error);
270 %feature("autodoc", "
271 Force a return from the frame passed in (and any frames younger than it)
272 without executing any more code in those frames. If return_value contains
273 a valid SBValue, that will be set as the return value from frame. Note, at
274 present only scalar return values are supported.") ReturnFromFrame;
277 ReturnFromFrame (SBFrame &frame, SBValue &return_value);
279 %feature("autodoc", "
280 Unwind the stack frames from the innermost expression evaluation.
281 This API is equivalent to 'thread return -x'.") UnwindInnermostExpression;
284 UnwindInnermostExpression();
286 %feature("docstring", "
287 LLDB currently supports process centric debugging which means when any
288 thread in a process stops, all other threads are stopped. The Suspend()
289 call here tells our process to suspend a thread and not let it run when
290 the other threads in a process are allowed to run. So when
291 SBProcess::Continue() is called, any threads that aren't suspended will
292 be allowed to run. If any of the SBThread functions for stepping are
293 called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
294 thread will now be allowed to run and these functions will simply return.
296 Eventually we plan to add support for thread centric debugging where
297 each thread is controlled individually and each thread would broadcast
298 its state, but we haven't implemented this yet.
300 Likewise the SBThread::Resume() call will again allow the thread to run
301 when the process is continued.
303 Suspend() and Resume() functions are not currently reference counted, if
304 anyone has the need for them to be reference counted, please let us
310 Suspend(SBError &error);
316 Resume (SBError &error);
328 GetFrameAtIndex (uint32_t idx);
334 SetSelectedFrame (uint32_t frame_idx);
340 GetDescription (lldb::SBStream &description) const;
342 %feature("docstring", "
343 Get the description strings for this thread that match what the
344 lldb driver will present, using the thread-format (stop_format==false)
345 or thread-stop-format (stop_format = true).") GetDescription;
346 bool GetDescription(lldb::SBStream &description, bool stop_format) const;
349 GetStatus (lldb::SBStream &status) const;
352 operator == (const lldb::SBThread &rhs) const;
355 operator != (const lldb::SBThread &rhs) const;
358 Given an argument of str to specify the type of thread-origin extended
359 backtrace to retrieve, query whether the origin of this thread is
360 available. An SBThread is retured; SBThread.IsValid will return true
361 if an extended backtrace was available. The returned SBThread is not
362 a part of the SBProcess' thread list and it cannot be manipulated like
363 normal threads -- you cannot step or resume it, for instance -- it is
364 intended to used primarily for generating a backtrace. You may request
365 the returned thread's own thread origin in turn.") GetExtendedBacktraceThread;
367 GetExtendedBacktraceThread (const char *type);
370 Takes no arguments, returns a uint32_t.
371 If this SBThread is an ExtendedBacktrace thread, get the IndexID of the
372 original thread that this ExtendedBacktrace thread represents, if
373 available. The thread that was running this backtrace in the past may
374 not have been registered with lldb's thread index (if it was created,
375 did its work, and was destroyed without lldb ever stopping execution).
376 In that case, this ExtendedBacktrace thread's IndexID will be returned.") GetExtendedBacktraceOriginatingIndexID;
378 GetExtendedBacktraceOriginatingIndexID();
381 Returns an SBValue object represeting the current exception for the thread,
382 if there is any. Currently, this works for Obj-C code and returns an SBValue
383 representing the NSException object at the throw site or that's currently
384 being processes.") GetCurrentException;
386 GetCurrentException();
389 Returns a historical (fake) SBThread representing the stack trace of an
390 exception, if there is one for the thread. Currently, this works for Obj-C
391 code, and can retrieve the throw-site backtrace of an NSException object
392 even when the program is no longer at the throw site.") GetCurrentExceptionBacktrace;
394 GetCurrentExceptionBacktrace();
397 Takes no arguments, returns a bool.
398 lldb may be able to detect that function calls should not be executed
399 on a given thread at a particular point in time. It is recommended that
400 this is checked before performing an inferior function call on a given
401 thread.") SafeToCallFunctions;
403 SafeToCallFunctions ();
405 STRING_EXTENSION(SBThread)
410 '''Iterate over all frames in a lldb.SBThread object.'''
411 return lldb_iter(self, 'GetNumFrames', 'GetFrameAtIndex')
414 '''Return the number of frames in a lldb.SBThread object.'''
415 return self.GetNumFrames()
417 class frames_access(object):
418 '''A helper object that will lazily hand out frames for a thread when supplied an index.'''
419 def __init__(self, sbthread):
420 self.sbthread = sbthread
424 return int(self.sbthread.GetNumFrames())
427 def __getitem__(self, key):
428 if type(key) is int and key < self.sbthread.GetNumFrames():
429 return self.sbthread.GetFrameAtIndex(key)
432 def get_frames_access_object(self):
433 '''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
434 return self.frames_access (self)
436 def get_thread_frames(self):
437 '''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
443 id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')
444 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.''')
445 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.''')
446 process = property(GetProcess, None, doc='''A read only property that returns an lldb object that represents the process (lldb.SBProcess) that owns this thread.''')
447 num_frames = property(GetNumFrames, None, doc='''A read only property that returns the number of stack frames in this thread as an integer.''')
448 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.''')
449 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]").''')
450 name = property(GetName, None, doc='''A read only property that returns the name of this thread as a string.''')
451 queue = property(GetQueueName, None, doc='''A read only property that returns the dispatch queue name of this thread as a string.''')
452 queue_id = property(GetQueueID, None, doc='''A read only property that returns the dispatch queue id of this thread as an integer.''')
453 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.''')
454 is_suspended = property(IsSuspended, None, doc='''A read only property that returns a boolean value that indicates if this thread is suspended.''')
455 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.''')