SBThread#

class lldb.SBThread(*args)#

Represents a thread of execution. SBProcess contains SBThread(s).

SBThreads can be referred to by their ID, which maps to the system specific thread identifier, or by IndexID. The ID may or may not be unique depending on whether the system reuses its thread identifiers. The IndexID is a monotonically increasing identifier that will always uniquely reference a particular thread, and when that thread goes away it will not be reused.

SBThread supports frame iteration. For example (from test/python_api/ lldbutil/iter/TestLLDBIterator.py),

from lldbutil import print_stacktrace
stopped_due_to_breakpoint = False
for thread in process:
    if self.TraceOn():
        print_stacktrace(thread)
    ID = thread.GetThreadID()
    if thread.GetStopReason() == lldb.eStopReasonBreakpoint:
        stopped_due_to_breakpoint = True
    for frame in thread:
        self.assertTrue(frame.GetThread().GetThreadID() == ID)
        if self.TraceOn():
            print frame

self.assertTrue(stopped_due_to_breakpoint)

See also SBFrame .

Attributes Summary

`eBroadcastBitSelectedFrameChanged`
`eBroadcastBitStackChanged`
`eBroadcastBitThreadResumed`
`eBroadcastBitThreadSelected`
`eBroadcastBitThreadSuspended`
`frame`	A read only property that returns an object that can be used to access frames as an array ("frame_12 = lldb.thread.frame[12]").
`frames`	A read only property that returns a list() of lldb.SBFrame objects for all frames in this thread.
`id`	A read only property that returns the thread ID as an integer.
`idx`	A read only property that returns the thread index ID as an integer.
`is_stopped`	A read only property that returns a boolean value that indicates if this thread is stopped but not exited.
`is_suspended`	A read only property that returns a boolean value that indicates if this thread is suspended.
`name`	A read only property that returns the name of this thread as a string.
`num_frames`	A read only property that returns the number of stack frames in this thread as an integer.
`process`	A read only property that returns an lldb object that represents the process (lldb.SBProcess) that owns this thread.
`queue`	A read only property that returns the dispatch queue name of this thread as a string.
`queue_id`	A read only property that returns the dispatch queue id of this thread as an integer.
`return_value`	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.
`stop_reason`	A read only property that returns an lldb enumeration value (see enumerations that start with "lldb.eStopReason") that represents the reason this thread stopped.

Methods Summary

`Clear`(SBThread self)
`EventIsThreadEvent`(SBEvent event)
`GetBroadcasterClassName`()
`GetCurrentException`(SBThread self)	Returns an SBValue object represeting the current exception for the thread, if there is any.
`GetCurrentExceptionBacktrace`(SBThread self)	Returns a historical (fake) SBThread representing the stack trace of an exception, if there is one for the thread.
`GetDescription`(-> bool)	Get the description strings for this thread that match what the lldb driver will present, using the thread-format (stop_format==false) or thread-stop-format (stop_format = true).
`GetDescriptionWithFormat`(SBThread self, ...)
`GetExtendedBacktraceOriginatingIndexID`(...)	If this SBThread is an ExtendedBacktrace thread, get the IndexID of the original thread that this ExtendedBacktrace thread represents, if available.
`GetExtendedBacktraceThread`(SBThread self, ...)	Given an argument of str to specify the type of thread-origin extended backtrace to retrieve, query whether the origin of this thread is available.
`GetFrameAtIndex`(SBThread self, uint32_t idx)
`GetIndexID`(SBThread self)	Return the index number for this SBThread.
`GetInfoItemByPathAsString`(SBThread self, ...)	Takes a path string and a SBStream reference as parameters, returns a bool.
`GetName`(SBThread self)
`GetNumFrames`(SBThread self)
`GetProcess`(SBThread self)
`GetQueue`(SBThread self)	Return the SBQueue for this thread.
`GetQueueID`(SBThread self)	Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
`GetQueueName`(SBThread self)	Return the queue name associated with this thread, if any, as a str.
`GetSelectedFrame`(SBThread self)
`GetSiginfo`(SBThread self)	Returns a SBValue object representing the siginfo for the current signal.
`GetStackFrameFromEvent`(SBEvent event)
`GetStatus`(SBThread self, SBStream status)
`GetStopDescription`(SBThread self, ...)	Pass only an (int)length and expect to get a Python string describing the stop reason.
`GetStopReason`(SBThread self)
`GetStopReasonDataAtIndex`(SBThread self, ...)	Get information associated with a stop reason.
`GetStopReasonDataCount`(SBThread self)	Get the number of words associated with the stop reason.
`GetStopReasonExtendedBacktraces`(...)	Returns a collection of historical stack traces that are significant to the current stop reason.
`GetStopReasonExtendedInfoAsJSON`(...)	Collects a thread's stop reason extended information dictionary and prints it into the SBStream in a JSON format.
`GetStopReturnValue`(SBThread self)
`GetThreadFromEvent`(SBEvent event)
`GetThreadID`(SBThread self)	Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type) for the current SBThread that will remain constant throughout the thread's lifetime in this process and will not be reused by another thread during this process lifetime.
`IsStopped`(SBThread self)
`IsSuspended`(SBThread self)
`IsValid`(SBThread self)
`JumpToLine`(SBThread self, ...)
`Resume`(-> bool)
`ReturnFromFrame`(SBThread self, ...)	Force a return from the frame passed in (and any frames younger than it) without executing any more code in those frames.
`RunToAddress`()
`SafeToCallFunctions`(SBThread self)	lldb may be able to detect that function calls should not be executed on a given thread at a particular point in time.
`SetSelectedFrame`(SBThread self, ...)
`StepInstruction`()	Do an instruction level single step in the currently selected thread.
`StepInto`(-> None)	Step the current thread from the current source line to the line given by end_line, stopping if the thread steps into the function given by target_name.
`StepOut`()	Step out of the currently selected thread.
`StepOutOfFrame`()	Step out of the specified frame.
`StepOver`()	Do a source level single step over in the currently selected thread.
`StepOverUntil`(SBThread self, SBFrame frame, ...)
`StepUsingScriptedThreadPlan`(...)
`Suspend`(-> bool)	LLDB currently supports process centric debugging which means when any thread in a process stops, all other threads are stopped.
`UnwindInnermostExpression`(SBThread self)	Unwind the stack frames from the innermost expression evaluation.
`get_frames_access_object`()	An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.
`get_thread_frames`()	An accessor function that returns a list() that contains all frames in a lldb.SBThread object.

Attributes Documentation

eBroadcastBitSelectedFrameChanged = <Mock name='mock.SBThread_eBroadcastBitSelectedFrameChanged' id='140712927586336'>#

eBroadcastBitStackChanged = <Mock name='mock.SBThread_eBroadcastBitStackChanged' id='140712927585952'>#

eBroadcastBitThreadResumed = <Mock name='mock.SBThread_eBroadcastBitThreadResumed' id='140712927586912'>#

eBroadcastBitThreadSelected = <Mock name='mock.SBThread_eBroadcastBitThreadSelected' id='140712927586480'>#

eBroadcastBitThreadSuspended = <Mock name='mock.SBThread_eBroadcastBitThreadSuspended' id='140712927586720'>#

frame#: A read only property that returns an object that can be used to access frames as an array (“frame_12 = lldb.thread.frame[12]”).

frames#: A read only property that returns a list() of lldb.SBFrame objects for all frames in this thread.

id#: A read only property that returns the thread ID as an integer.

idx#: 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.

is_stopped#: A read only property that returns a boolean value that indicates if this thread is stopped but not exited.

is_suspended#: A read only property that returns a boolean value that indicates if this thread is suspended.

name#: A read only property that returns the name of this thread as a string.

num_frames#: A read only property that returns the number of stack frames in this thread as an integer.

process#: A read only property that returns an lldb object that represents the process (lldb.SBProcess) that owns this thread.

queue#: A read only property that returns the dispatch queue name of this thread as a string.

queue_id#: A read only property that returns the dispatch queue id of this thread as an integer.

return_value#: 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.

stop_reason#: A read only property that returns an lldb enumeration value (see enumerations that start with “lldb.eStopReason”) that represents the reason this thread stopped.

Methods Documentation

Clear(SBThread self)#

static EventIsThreadEvent(SBEvent event) → bool#

static GetBroadcasterClassName() → char const *#

GetCurrentException(SBThread self) → SBValue#: Returns an SBValue object represeting the current exception for the thread, if there is any. Currently, this works for Obj-C code and returns an SBValue representing the NSException object at the throw site or that’s currently being processes.

GetCurrentExceptionBacktrace(SBThread self) → SBThread#: Returns a historical (fake) SBThread representing the stack trace of an exception, if there is one for the thread. Currently, this works for Obj-C code, and can retrieve the throw-site backtrace of an NSException object even when the program is no longer at the throw site.

GetDescription(SBThread self, SBStream description) → bool#
GetDescription(SBThread self, SBStream description, bool stop_format) → bool: Get the description strings for this thread that match what the lldb driver will present, using the thread-format (stop_format==false) or thread-stop-format (stop_format = true).

GetDescriptionWithFormat(SBThread self, SBFormat format, SBStream output) → SBError#

GetExtendedBacktraceOriginatingIndexID(SBThread self) → uint32_t#: If this SBThread is an ExtendedBacktrace thread, get the IndexID of the original thread that this ExtendedBacktrace thread represents, if available. The thread that was running this backtrace in the past may not have been registered with lldb’s thread index (if it was created, did its work, and was destroyed without lldb ever stopping execution). In that case, this ExtendedBacktrace thread’s IndexID will be returned.

GetExtendedBacktraceThread(SBThread self, char const * type) → SBThread#: Given an argument of str to specify the type of thread-origin extended backtrace to retrieve, query whether the origin of this thread is available. An SBThread is retured; SBThread.IsValid will return true if an extended backtrace was available. The returned SBThread is not a part of the SBProcess’ thread list and it cannot be manipulated like normal threads – you cannot step or resume it, for instance – it is intended to used primarily for generating a backtrace. You may request the returned thread’s own thread origin in turn.

GetFrameAtIndex(SBThread self, uint32_t idx) → SBFrame#

GetIndexID(SBThread self) → uint32_t#: Return the index number for this SBThread. The index number is the same thing that a user gives as an argument to ‘thread select’ in the command line lldb. These numbers start at 1 (for the first thread lldb sees in a debug session) and increments up throughout the process lifetime. An index number will not be reused for a different thread later in a process - thread 1 will always be associated with the same thread. See related GetThreadID. This method returns a uint32_t index number, takes no arguments.

GetInfoItemByPathAsString(SBThread self, char const * path, SBStream strm) → bool#: Takes a path string and a SBStream reference as parameters, returns a bool. Collects the thread’s ‘info’ dictionary from the remote system, uses the path argument to descend into the dictionary to an item of interest, and prints it into the SBStream in a natural format. Return bool is to indicate if anything was printed into the stream (true) or not (false).

GetName(SBThread self) → char const *#

GetNumFrames(SBThread self) → uint32_t#

GetProcess(SBThread self) → SBProcess#

GetQueue(SBThread self) → SBQueue#: Return the SBQueue for this thread. If this thread is not currently associated with a libdispatch queue, the SBQueue object’s IsValid() method will return false. If this SBThread is actually a HistoryThread, we may be able to provide QueueID and QueueName, but not provide an SBQueue. Those individual attributes may have been saved for the HistoryThread without enough information to reconstitute the entire SBQueue at that time. This method takes no arguments, returns an SBQueue.

GetQueueID(SBThread self) → lldb::queue_id_t#: Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t. For example, with a libdispatch (aka Grand Central Dispatch) queue.

GetQueueName(SBThread self) → char const *#: Return the queue name associated with this thread, if any, as a str. For example, with a libdispatch (aka Grand Central Dispatch) queue.

GetSelectedFrame(SBThread self) → SBFrame#

GetSiginfo(SBThread self) → SBValue#: Returns a SBValue object representing the siginfo for the current signal.

static GetStackFrameFromEvent(SBEvent event) → SBFrame#

GetStatus(SBThread self, SBStream status) → bool#

GetStopDescription(SBThread self, char * dst_or_null) → size_t#: Pass only an (int)length and expect to get a Python string describing the stop reason.

GetStopReason(SBThread self) → lldb::StopReason#

GetStopReasonDataAtIndex(SBThread self, uint32_t idx) → uint64_t#

Get information associated with a stop reason.

Breakpoint stop reasons will have data that consists of pairs of breakpoint IDs followed by the breakpoint location IDs (they always come in pairs).

Stop Reason Count Data Type ======================== ===== ========================================= eStopReasonNone 0 eStopReasonTrace 0 eStopReasonBreakpoint N duple: {breakpoint id, location id} eStopReasonWatchpoint 1 watchpoint id eStopReasonSignal 1 unix signal number eStopReasonException N exception data eStopReasonExec 0 eStopReasonFork 1 pid of the child process eStopReasonVFork 1 pid of the child process eStopReasonVForkDone 0 eStopReasonPlanComplete 0

GetStopReasonDataCount(SBThread self) → size_t#: Get the number of words associated with the stop reason. See also GetStopReasonDataAtIndex().

GetStopReasonExtendedBacktraces(SBThread self, lldb::InstrumentationRuntimeType type) → SBThreadCollection#: Returns a collection of historical stack traces that are significant to the current stop reason. Used by ThreadSanitizer, where we provide various stack traces that were involved in a data race or other type of detected issue.

GetStopReasonExtendedInfoAsJSON(SBThread self, SBStream stream) → bool#: Collects a thread’s stop reason extended information dictionary and prints it into the SBStream in a JSON format. The format of this JSON dictionary depends on the stop reason and is currently used only for instrumentation plugins.

GetStopReturnValue(SBThread self) → SBValue#

static GetThreadFromEvent(SBEvent event) → SBThread#

GetThreadID(SBThread self) → lldb::tid_t#: Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type) for the current SBThread that will remain constant throughout the thread’s lifetime in this process and will not be reused by another thread during this process lifetime. On Mac OS X systems, this is a system-wide unique thread identifier; this identifier is also used by other tools like sample which helps to associate data from those tools with lldb. See related GetIndexID.

IsStopped(SBThread self) → bool#

IsSuspended(SBThread self) → bool#

IsValid(SBThread self) → bool#

JumpToLine(SBThread self, SBFileSpec file_spec, uint32_t line) → SBError#

Resume(SBThread self) → bool#
Resume(SBThread self, SBError error) → bool

ReturnFromFrame(SBThread self, SBFrame frame, SBValue return_value) → SBError#: Force a return from the frame passed in (and any frames younger than it) without executing any more code in those frames. If return_value contains a valid SBValue, that will be set as the return value from frame. Note, at present only scalar return values are supported.

RunToAddress(SBThread self, lldb::addr_t addr)#
RunToAddress(SBThread self, lldb::addr_t addr, SBError error) → None

SafeToCallFunctions(SBThread self) → bool#: lldb may be able to detect that function calls should not be executed on a given thread at a particular point in time. It is recommended that this is checked before performing an inferior function call on a given thread.

SetSelectedFrame(SBThread self, uint32_t frame_idx) → SBFrame#

StepInstruction(SBThread self, bool step_over)#
StepInstruction(SBThread self, bool step_over, SBError error) → None: Do an instruction level single step in the currently selected thread.

StepInto(SBThread self, lldb::RunMode stop_other_threads=eOnlyDuringStepping)#
StepInto(SBThread self, char const * target_name, lldb::RunMode stop_other_threads=eOnlyDuringStepping) → None
StepInto(SBThread self, char const * target_name, uint32_t end_line, SBError error, lldb::RunMode stop_other_threads=eOnlyDuringStepping) → None: Step the current thread from the current source line to the line given by end_line, stopping if the thread steps into the function given by target_name. If target_name is None, then stepping will stop in any of the places we would normally stop.

StepOut(SBThread self)#
StepOut(SBThread self, SBError error) → None: Step out of the currently selected thread.

StepOutOfFrame(SBThread self, SBFrame frame)#
StepOutOfFrame(SBThread self, SBFrame frame, SBError error) → None: Step out of the specified frame.

StepOver(SBThread self, lldb::RunMode stop_other_threads=eOnlyDuringStepping)#
StepOver(SBThread self, lldb::RunMode stop_other_threads, SBError error) → None: Do a source level single step over in the currently selected thread.

StepOverUntil(SBThread self, SBFrame frame, SBFileSpec file_spec, uint32_t line) → SBError#

StepUsingScriptedThreadPlan(SBThread self, char const * script_class_name) → SBError#
StepUsingScriptedThreadPlan(SBThread self, char const * script_class_name, bool resume_immediately) → SBError
StepUsingScriptedThreadPlan(SBThread self, char const * script_class_name, SBStructuredData args_data, bool resume_immediately) → SBError

Suspend(SBThread self) → bool#

Suspend(SBThread self, SBError error) → bool

LLDB currently supports process centric debugging which means when any thread in a process stops, all other threads are stopped. The Suspend() call here tells our process to suspend a thread and not let it run when the other threads in a process are allowed to run. So when SBProcess::Continue() is called, any threads that aren’t suspended will be allowed to run. If any of the SBThread functions for stepping are called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the thread will now be allowed to run and these functions will simply return.

Eventually we plan to add support for thread centric debugging where each thread is controlled individually and each thread would broadcast its state, but we haven’t implemented this yet.

Likewise the SBThread::Resume() call will again allow the thread to run when the process is continued.

Suspend() and Resume() functions are not currently reference counted, if anyone has the need for them to be reference counted, please let us know.

UnwindInnermostExpression(SBThread self) → SBError#: Unwind the stack frames from the innermost expression evaluation. This API is equivalent to ‘thread return -x’.

get_frames_access_object()#: An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.

get_thread_frames()#: An accessor function that returns a list() that contains all frames in a lldb.SBThread object.