diff options
Diffstat (limited to 'scripts/interface/SBThread.i')
| -rw-r--r-- | scripts/interface/SBThread.i | 408 |
1 files changed, 408 insertions, 0 deletions
diff --git a/scripts/interface/SBThread.i b/scripts/interface/SBThread.i new file mode 100644 index 000000000000..f2b27565d489 --- /dev/null +++ b/scripts/interface/SBThread.i @@ -0,0 +1,408 @@ +//===-- 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", " + 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("autodoc", " + 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); + + 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 + 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("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; + + 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 |