1 //===-- SWIG Interface for SBThread -----------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
13 "Represents a thread of execution. SBProcess contains SBThread(s).
15 SBThreads can be referred to by their ID, which maps to the system specific thread
16 identifier, or by IndexID. The ID may or may not be unique depending on whether the
17 system reuses its thread identifiers. The IndexID is a monotonically increasing identifier
18 that will always uniquely reference a particular thread, and when that thread goes
19 away it will not be reused.
21 SBThread supports frame iteration. For example (from test/python_api/
22 lldbutil/iter/TestLLDBIterator.py),
24 from lldbutil import print_stacktrace
25 stopped_due_to_breakpoint = False
26 for thread in process:
28 print_stacktrace(thread)
29 ID = thread.GetThreadID()
30 if thread.GetStopReason() == lldb.eStopReasonBreakpoint:
31 stopped_due_to_breakpoint = True
33 self.assertTrue(frame.GetThread().GetThreadID() == ID)
37 self.assertTrue(stopped_due_to_breakpoint)
39 See also SBProcess and SBFrame."
44 //------------------------------------------------------------------
46 //------------------------------------------------------------------
49 eBroadcastBitStackChanged = (1 << 0),
50 eBroadcastBitThreadSuspended = (1 << 1),
51 eBroadcastBitThreadResumed = (1 << 2),
52 eBroadcastBitSelectedFrameChanged = (1 << 3),
53 eBroadcastBitThreadSelected = (1 << 4)
59 SBThread (const lldb::SBThread &thread);
64 GetBroadcasterClassName ();
67 EventIsThreadEvent (const SBEvent &event);
70 GetStackFrameFromEvent (const SBEvent &event);
73 GetThreadFromEvent (const SBEvent &event);
84 %feature("docstring", "
85 /// Get the number of words associated with the stop reason.
86 /// See also GetStopReasonDataAtIndex().
87 ") GetStopReasonDataCount;
89 GetStopReasonDataCount();
91 %feature("docstring", "
92 //--------------------------------------------------------------------------
93 /// Get information associated with a stop reason.
95 /// Breakpoint stop reasons will have data that consists of pairs of
96 /// breakpoint IDs followed by the breakpoint location IDs (they always come
99 /// Stop Reason Count Data Type
100 /// ======================== ===== =========================================
101 /// eStopReasonNone 0
102 /// eStopReasonTrace 0
103 /// eStopReasonBreakpoint N duple: {breakpoint id, location id}
104 /// eStopReasonWatchpoint 1 watchpoint id
105 /// eStopReasonSignal 1 unix signal number
106 /// eStopReasonException N exception data
107 /// eStopReasonExec 0
108 /// eStopReasonPlanComplete 0
109 //--------------------------------------------------------------------------
110 ") GetStopReasonDataAtIndex;
112 GetStopReasonDataAtIndex(uint32_t idx);
114 %feature("autodoc", "
115 Collects a thread's stop reason extended information dictionary and prints it
116 into the SBStream in a JSON format. The format of this JSON dictionary depends
117 on the stop reason and is currently used only for instrumentation plugins.
118 ") GetStopReasonExtendedInfoAsJSON;
120 GetStopReasonExtendedInfoAsJSON (lldb::SBStream &stream);
122 %feature("autodoc", "
123 Returns a collection of historical stack traces that are significant to the
124 current stop reason. Used by ThreadSanitizer, where we provide various stack
125 traces that were involved in a data race or other type of detected issue.
126 ") GetStopReasonExtendedBacktraces;
128 GetStopReasonExtendedBacktraces (InstrumentationRuntimeType type);
131 %feature("autodoc", "
132 Pass only an (int)length and expect to get a Python string describing the
134 ") GetStopDescription;
136 GetStopDescription (char *dst, size_t dst_len);
139 GetStopReturnValue ();
141 %feature("autodoc", "
142 Returns a unique thread identifier (type lldb::tid_t, typically a 64-bit type)
143 for the current SBThread that will remain constant throughout the thread's
144 lifetime in this process and will not be reused by another thread during this
145 process lifetime. On Mac OS X systems, this is a system-wide unique thread
146 identifier; this identifier is also used by other tools like sample which helps
147 to associate data from those tools with lldb. See related GetIndexID.
151 GetThreadID () const;
153 %feature("autodoc", "
154 Return the index number for this SBThread. The index number is the same thing
155 that a user gives as an argument to 'thread select' in the command line lldb.
156 These numbers start at 1 (for the first thread lldb sees in a debug session)
157 and increments up throughout the process lifetime. An index number will not be
158 reused for a different thread later in a process - thread 1 will always be
159 associated with the same thread. See related GetThreadID.
160 This method returns a uint32_t index number, takes no arguments.
169 %feature("autodoc", "
170 Return the queue name associated with this thread, if any, as a str.
171 For example, with a libdispatch (aka Grand Central Dispatch) queue.
175 GetQueueName() const;
177 %feature("autodoc", "
178 Return the dispatch_queue_id for this thread, if any, as a lldb::queue_id_t.
179 For example, with a libdispatch (aka Grand Central Dispatch) queue.
185 %feature("autodoc", "
186 Takes a path string and a SBStream reference as parameters, returns a bool.
187 Collects the thread's 'info' dictionary from the remote system, uses the path
188 argument to descend into the dictionary to an item of interest, and prints
189 it into the SBStream in a natural format. Return bool is to indicate if
190 anything was printed into the stream (true) or not (false).
191 ") GetInfoItemByPathAsString;
194 GetInfoItemByPathAsString (const char *path, lldb::SBStream &strm);
196 %feature("autodoc", "
197 Return the SBQueue for this thread. If this thread is not currently associated
198 with a libdispatch queue, the SBQueue object's IsValid() method will return false.
199 If this SBThread is actually a HistoryThread, we may be able to provide QueueID
200 and QueueName, but not provide an SBQueue. Those individual attributes may have
201 been saved for the HistoryThread without enough information to reconstitute the
202 entire SBQueue at that time.
203 This method takes no arguments, returns an SBQueue.
210 StepOver (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
213 StepInto (lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
216 StepInto (const char *target_name, lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
218 %feature("autodoc", "
219 Step the current thread from the current source line to the line given by end_line, stopping if
220 the thread steps into the function given by target_name. If target_name is None, then stepping will stop
221 in any of the places we would normally stop.
224 StepInto (const char *target_name,
227 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
233 StepOutOfFrame (lldb::SBFrame &frame);
236 StepInstruction(bool step_over);
239 StepOverUntil (lldb::SBFrame &frame,
240 lldb::SBFileSpec &file_spec,
244 StepUsingScriptedThreadPlan (const char *script_class_name);
247 StepUsingScriptedThreadPlan (const char *script_class_name, bool resume_immediately);
250 JumpToLine (lldb::SBFileSpec &file_spec, uint32_t line);
253 RunToAddress (lldb::addr_t addr);
255 %feature("autodoc", "
256 Force a return from the frame passed in (and any frames younger than it)
257 without executing any more code in those frames. If return_value contains
258 a valid SBValue, that will be set as the return value from frame. Note, at
259 present only scalar return values are supported.
263 ReturnFromFrame (SBFrame &frame, SBValue &return_value);
265 %feature("autodoc", "
266 Unwind the stack frames from the innermost expression evaluation.
267 This API is equivalent to 'thread return -x'.
268 ") UnwindInnermostExpression;
271 UnwindInnermostExpression();
273 %feature("docstring", "
274 //--------------------------------------------------------------------------
275 /// LLDB currently supports process centric debugging which means when any
276 /// thread in a process stops, all other threads are stopped. The Suspend()
277 /// call here tells our process to suspend a thread and not let it run when
278 /// the other threads in a process are allowed to run. So when
279 /// SBProcess::Continue() is called, any threads that aren't suspended will
280 /// be allowed to run. If any of the SBThread functions for stepping are
281 /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddres), the
282 /// thread will now be allowed to run and these functions will simply return.
284 /// Eventually we plan to add support for thread centric debugging where
285 /// each thread is controlled individually and each thread would broadcast
286 /// its state, but we haven't implemented this yet.
288 /// Likewise the SBThread::Resume() call will again allow the thread to run
289 /// when the process is continued.
291 /// Suspend() and Resume() functions are not currently reference counted, if
292 /// anyone has the need for them to be reference counted, please let us
294 //--------------------------------------------------------------------------
312 GetFrameAtIndex (uint32_t idx);
318 SetSelectedFrame (uint32_t frame_idx);
324 GetDescription (lldb::SBStream &description) const;
326 %feature("docstring", "
327 //--------------------------------------------------------------------------
328 /// Get the description strings for this thread that match what the
329 /// lldb driver will present, using the thread-format (stop_format==false)
330 /// or thread-stop-format (stop_format = true).
\13
331 //--------------------------------------------------------------------------
333 bool GetDescription(lldb::SBStream &description, bool stop_format) const;
336 GetStatus (lldb::SBStream &status) const;
339 operator == (const lldb::SBThread &rhs) const;
342 operator != (const lldb::SBThread &rhs) const;
345 Given an argument of str to specify the type of thread-origin extended
346 backtrace to retrieve, query whether the origin of this thread is
347 available. An SBThread is retured; SBThread.IsValid will return true
348 if an extended backtrace was available. The returned SBThread is not
349 a part of the SBProcess' thread list and it cannot be manipulated like
350 normal threads -- you cannot step or resume it, for instance -- it is
351 intended to used primarily for generating a backtrace. You may request
352 the returned thread's own thread origin in turn.
353 ") GetExtendedBacktraceThread;
355 GetExtendedBacktraceThread (const char *type);
358 Takes no arguments, returns a uint32_t.
359 If this SBThread is an ExtendedBacktrace thread, get the IndexID of the
360 original thread that this ExtendedBacktrace thread represents, if
361 available. The thread that was running this backtrace in the past may
362 not have been registered with lldb's thread index (if it was created,
363 did its work, and was destroyed without lldb ever stopping execution).
364 In that case, this ExtendedBacktrace thread's IndexID will be returned.
365 ") GetExtendedBacktraceOriginatingIndexID;
367 GetExtendedBacktraceOriginatingIndexID();
370 Takes no arguments, returns a bool.
371 lldb may be able to detect that function calls should not be executed
372 on a given thread at a particular point in time. It is recommended that
373 this is checked before performing an inferior function call on a given
375 ") SafeToCallFunctions;
377 SafeToCallFunctions ();
380 class frames_access(object):
381 '''A helper object that will lazily hand out frames for a thread when supplied an index.'''
382 def __init__(self, sbthread):
383 self.sbthread = sbthread
387 return int(self.sbthread.GetNumFrames())
390 def __getitem__(self, key):
391 if type(key) is int and key < self.sbthread.GetNumFrames():
392 return self.sbthread.GetFrameAtIndex(key)
395 def get_frames_access_object(self):
396 '''An accessor function that returns a frames_access() object which allows lazy frame access from a lldb.SBThread object.'''
397 return self.frames_access (self)
399 def get_thread_frames(self):
400 '''An accessor function that returns a list() that contains all frames in a lldb.SBThread object.'''
406 __swig_getmethods__["id"] = GetThreadID
407 if _newclass: id = property(GetThreadID, None, doc='''A read only property that returns the thread ID as an integer.''')
409 __swig_getmethods__["idx"] = GetIndexID
410 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.''')
412 __swig_getmethods__["return_value"] = GetStopReturnValue
413 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.''')
415 __swig_getmethods__["process"] = GetProcess
416 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.''')
418 __swig_getmethods__["num_frames"] = GetNumFrames
419 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.''')
421 __swig_getmethods__["frames"] = get_thread_frames
422 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.''')
424 __swig_getmethods__["frame"] = get_frames_access_object
425 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]").''')
427 __swig_getmethods__["name"] = GetName
428 if _newclass: name = property(GetName, None, doc='''A read only property that returns the name of this thread as a string.''')
430 __swig_getmethods__["queue"] = GetQueueName
431 if _newclass: queue = property(GetQueueName, None, doc='''A read only property that returns the dispatch queue name of this thread as a string.''')
433 __swig_getmethods__["queue_id"] = GetQueueID
434 if _newclass: queue_id = property(GetQueueID, None, doc='''A read only property that returns the dispatch queue id of this thread as an integer.''')
436 __swig_getmethods__["stop_reason"] = GetStopReason
437 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.''')
439 __swig_getmethods__["is_suspended"] = IsSuspended
440 if _newclass: is_suspended = property(IsSuspended, None, doc='''A read only property that returns a boolean value that indicates if this thread is suspended.''')
442 __swig_getmethods__["is_stopped"] = IsStopped
443 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.''')