forked from OSchip/llvm-project
451 lines
18 KiB
C++
451 lines
18 KiB
C++
//===-- SWIG Interface for SBThread -----------------------------*- C++ -*-===//
|
|
//
|
|
// The LLVM Compiler Infrastructure
|
|
//
|
|
// This file is distributed under the University of Illinois Open Source
|
|
// License. See LICENSE.TXT for details.
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
namespace lldb {
|
|
|
|
%feature("docstring",
|
|
"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 SBProcess and SBFrame."
|
|
) SBThread;
|
|
class SBThread
|
|
{
|
|
public:
|
|
//------------------------------------------------------------------
|
|
// Broadcaster bits.
|
|
//------------------------------------------------------------------
|
|
enum
|
|
{
|
|
eBroadcastBitStackChanged = (1 << 0),
|
|
eBroadcastBitThreadSuspended = (1 << 1),
|
|
eBroadcastBitThreadResumed = (1 << 2),
|
|
eBroadcastBitSelectedFrameChanged = (1 << 3),
|
|
eBroadcastBitThreadSelected = (1 << 4)
|
|
};
|
|
|
|
|
|
SBThread ();
|
|
|
|
SBThread (const lldb::SBThread &thread);
|
|
|
|
~SBThread();
|
|
|
|
static const char *
|
|
GetBroadcasterClassName ();
|
|
|
|
static bool
|
|
EventIsThreadEvent (const SBEvent &event);
|
|
|
|
static SBFrame
|
|
GetStackFrameFromEvent (const SBEvent &event);
|
|
|
|
static SBThread
|
|
GetThreadFromEvent (const SBEvent &event);
|
|
|
|
bool
|
|
IsValid() const;
|
|
|
|
void
|
|
Clear ();
|
|
|
|
lldb::StopReason
|
|
GetStopReason();
|
|
|
|
%feature("docstring", "
|
|
/// Get the number of words associated with the stop reason.
|
|
/// See also GetStopReasonDataAtIndex().
|
|
") GetStopReasonDataCount;
|
|
size_t
|
|
GetStopReasonDataCount();
|
|
|
|
%feature("docstring", "
|
|
//--------------------------------------------------------------------------
|
|
/// 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
|
|
/// eStopReasonPlanComplete 0
|
|
//--------------------------------------------------------------------------
|
|
") GetStopReasonDataAtIndex;
|
|
uint64_t
|
|
GetStopReasonDataAtIndex(uint32_t idx);
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") GetStopReasonExtendedInfoAsJSON;
|
|
bool
|
|
GetStopReasonExtendedInfoAsJSON (lldb::SBStream &stream);
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") GetStopReasonExtendedBacktraces;
|
|
SBThreadCollection
|
|
GetStopReasonExtendedBacktraces (InstrumentationRuntimeType type);
|
|
|
|
|
|
%feature("autodoc", "
|
|
Pass only an (int)length and expect to get a Python string describing the
|
|
stop reason.
|
|
") GetStopDescription;
|
|
size_t
|
|
GetStopDescription (char *dst, size_t dst_len);
|
|
|
|
SBValue
|
|
GetStopReturnValue ();
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
")
|
|
GetThreadID;
|
|
lldb::tid_t
|
|
GetThreadID () const;
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
")
|
|
GetIndexID;
|
|
uint32_t
|
|
GetIndexID () const;
|
|
|
|
const char *
|
|
GetName () const;
|
|
|
|
%feature("autodoc", "
|
|
Return the queue name associated with this thread, if any, as a str.
|
|
For example, with a libdispatch (aka Grand Central Dispatch) queue.
|
|
") GetQueueName;
|
|
|
|
const char *
|
|
GetQueueName() const;
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") GetQueueID;
|
|
|
|
lldb::queue_id_t
|
|
GetQueueID() const;
|
|
|
|
%feature("docstring", "
|
|
//--------------------------------------------------------------------------
|
|
/// 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).
|
|
//--------------------------------------------------------------------------
|
|
") GetInfoItemByPathAsString;
|
|
|
|
bool
|
|
GetInfoItemByPathAsString (const char *path, lldb::SBStream &strm);
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") GetQueue;
|
|
|
|
lldb::SBQueue
|
|
GetQueue () const;
|
|
|
|
void
|
|
StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
|
|
|
|
void
|
|
StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
|
|
|
|
void
|
|
StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") StepInto;
|
|
void
|
|
StepInto (const char *target_name,
|
|
uint32_t end_line,
|
|
SBError &error,
|
|
lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
|
|
|
|
void
|
|
StepOut ();
|
|
|
|
void
|
|
StepOutOfFrame (lldb::SBFrame &frame);
|
|
|
|
void
|
|
StepInstruction(bool step_over);
|
|
|
|
SBError
|
|
StepOverUntil (lldb::SBFrame &frame,
|
|
lldb::SBFileSpec &file_spec,
|
|
uint32_t line);
|
|
|
|
SBError
|
|
StepUsingScriptedThreadPlan (const char *script_class_name);
|
|
|
|
SBError
|
|
StepUsingScriptedThreadPlan (const char *script_class_name, bool resume_immediately);
|
|
|
|
SBError
|
|
JumpToLine (lldb::SBFileSpec &file_spec, uint32_t line);
|
|
|
|
void
|
|
RunToAddress (lldb::addr_t addr);
|
|
|
|
%feature("autodoc", "
|
|
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.
|
|
") ReturnFromFrame;
|
|
|
|
SBError
|
|
ReturnFromFrame (SBFrame &frame, SBValue &return_value);
|
|
|
|
%feature("autodoc", "
|
|
Unwind the stack frames from the innermost expression evaluation.
|
|
This API is equivalent to 'thread return -x'.
|
|
") UnwindInnermostExpression;
|
|
|
|
SBError
|
|
UnwindInnermostExpression();
|
|
|
|
%feature("docstring", "
|
|
//--------------------------------------------------------------------------
|
|
/// 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.
|
|
//--------------------------------------------------------------------------
|
|
") Suspend;
|
|
bool
|
|
Suspend();
|
|
|
|
bool
|
|
Resume ();
|
|
|
|
bool
|
|
IsSuspended();
|
|
|
|
bool
|
|
IsStopped();
|
|
|
|
uint32_t
|
|
GetNumFrames ();
|
|
|
|
lldb::SBFrame
|
|
GetFrameAtIndex (uint32_t idx);
|
|
|
|
lldb::SBFrame
|
|
GetSelectedFrame ();
|
|
|
|
lldb::SBFrame
|
|
SetSelectedFrame (uint32_t frame_idx);
|
|
|
|
lldb::SBProcess
|
|
GetProcess ();
|
|
|
|
bool
|
|
GetDescription (lldb::SBStream &description) const;
|
|
|
|
%feature("docstring", "
|
|
//--------------------------------------------------------------------------
|
|
/// 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).
|
|
//--------------------------------------------------------------------------
|
|
") GetDescription;
|
|
bool GetDescription(lldb::SBStream &description, bool stop_format) const;
|
|
|
|
bool
|
|
GetStatus (lldb::SBStream &status) const;
|
|
|
|
bool
|
|
operator == (const lldb::SBThread &rhs) const;
|
|
|
|
bool
|
|
operator != (const lldb::SBThread &rhs) const;
|
|
|
|
%feature("autodoc","
|
|
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.
|
|
") GetExtendedBacktraceThread;
|
|
lldb::SBThread
|
|
GetExtendedBacktraceThread (const char *type);
|
|
|
|
%feature("autodoc","
|
|
Takes no arguments, returns a 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.
|
|
") GetExtendedBacktraceOriginatingIndexID;
|
|
uint32_t
|
|
GetExtendedBacktraceOriginatingIndexID();
|
|
|
|
%feature("autodoc","
|
|
Takes no arguments, returns a 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.
|
|
") SafeToCallFunctions;
|
|
bool
|
|
SafeToCallFunctions ();
|
|
|
|
%pythoncode %{
|
|
class frames_access(object):
|
|
'''A helper object that will lazily hand out frames for a thread when supplied an index.'''
|
|
def __init__(self, sbthread):
|
|
self.sbthread = sbthread
|
|
|
|
def __len__(self):
|
|
if self.sbthread:
|
|
return int(self.sbthread.GetNumFrames())
|
|
return 0
|
|
|
|
def __getitem__(self, key):
|
|
if type(key) is int and key < self.sbthread.GetNumFrames():
|
|
return self.sbthread.GetFrameAtIndex(key)
|
|
return None
|
|
|
|
def get_frames_access_object(self):
|
|
'''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
|
|
return self.frames_access (self)
|
|
|
|
def get_thread_frames(self):
|
|
'''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
|
|
frames = []
|
|
for frame in self:
|
|
frames.append(frame)
|
|
return frames
|
|
|
|
__swig_getmethods__["id"] = GetThreadID
|
|
if _newclass: id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')
|
|
|
|
__swig_getmethods__["idx"] = GetIndexID
|
|
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.''')
|
|
|
|
__swig_getmethods__["return_value"] = GetStopReturnValue
|
|
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.''')
|
|
|
|
__swig_getmethods__["process"] = GetProcess
|
|
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.''')
|
|
|
|
__swig_getmethods__["num_frames"] = GetNumFrames
|
|
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.''')
|
|
|
|
__swig_getmethods__["frames"] = get_thread_frames
|
|
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.''')
|
|
|
|
__swig_getmethods__["frame"] = get_frames_access_object
|
|
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]").''')
|
|
|
|
__swig_getmethods__["name"] = GetName
|
|
if _newclass: name = property(GetName, None, doc='''A read only property that returns the name of this thread as a string.''')
|
|
|
|
__swig_getmethods__["queue"] = GetQueueName
|
|
if _newclass: queue = property(GetQueueName, None, doc='''A read only property that returns the dispatch queue name of this thread as a string.''')
|
|
|
|
__swig_getmethods__["queue_id"] = GetQueueID
|
|
if _newclass: queue_id = property(GetQueueID, None, doc='''A read only property that returns the dispatch queue id of this thread as an integer.''')
|
|
|
|
__swig_getmethods__["stop_reason"] = GetStopReason
|
|
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.''')
|
|
|
|
__swig_getmethods__["is_suspended"] = IsSuspended
|
|
if _newclass: is_suspended = property(IsSuspended, None, doc='''A read only property that returns a boolean value that indicates if this thread is suspended.''')
|
|
|
|
__swig_getmethods__["is_stopped"] = IsStopped
|
|
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.''')
|
|
%}
|
|
|
|
};
|
|
|
|
} // namespace lldb
|