lldb/API/SBThread.h

0001 //===-- SBThread.h ----------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_API_SBTHREAD_H
0010 #define LLDB_API_SBTHREAD_H
0011
0012 #include "lldb/API/SBDefines.h"
0013
0014 #include <cstdio>
0015
0016 namespace lldb_private {
0017 namespace python {
0018 class SWIGBridge;
0019 }
0020 } // namespace lldb_private
0021
0022 namespace lldb {
0023
0024 class SBFrame;
0025
0026 class LLDB_API SBThread {
0027 public:
0028   enum {
0029     eBroadcastBitStackChanged = (1 << 0),
0030     eBroadcastBitThreadSuspended = (1 << 1),
0031     eBroadcastBitThreadResumed = (1 << 2),
0032     eBroadcastBitSelectedFrameChanged = (1 << 3),
0033     eBroadcastBitThreadSelected = (1 << 4)
0034   };
0035
0036   static const char *GetBroadcasterClassName();
0037
0038   SBThread();
0039
0040   SBThread(const lldb::SBThread &thread);
0041
0042   ~SBThread();
0043
0044   lldb::SBQueue GetQueue() const;
0045
0046   explicit operator bool() const;
0047
0048   bool IsValid() const;
0049
0050   void Clear();
0051
0052   lldb::StopReason GetStopReason();
0053
0054   /// Get the number of words associated with the stop reason.
0055   /// See also GetStopReasonDataAtIndex().
0056   size_t GetStopReasonDataCount();
0057
0058   /// Get information associated with a stop reason.
0059   ///
0060   /// Breakpoint stop reasons will have data that consists of pairs of
0061   /// breakpoint IDs followed by the breakpoint location IDs (they always come
0062   /// in pairs).
0063   ///
0064   /// Stop Reason              Count Data Type
0065   /// ======================== ===== =========================================
0066   /// eStopReasonNone          0
0067   /// eStopReasonTrace         0
0068   /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
0069   /// eStopReasonWatchpoint    1     watchpoint id
0070   /// eStopReasonSignal        1     unix signal number
0071   /// eStopReasonException     N     exception data
0072   /// eStopReasonExec          0
0073   /// eStopReasonFork          1     pid of the child process
0074   /// eStopReasonVFork         1     pid of the child process
0075   /// eStopReasonVForkDone     0
0076   /// eStopReasonPlanComplete  0
0077   uint64_t GetStopReasonDataAtIndex(uint32_t idx);
0078
0079   bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream);
0080
0081   SBThreadCollection
0082   GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type);
0083
0084   size_t GetStopDescription(char *dst_or_null, size_t dst_len);
0085
0086   SBValue GetStopReturnValue();
0087
0088   lldb::tid_t GetThreadID() const;
0089
0090   uint32_t GetIndexID() const;
0091
0092   const char *GetName() const;
0093
0094   const char *GetQueueName() const;
0095
0096   lldb::queue_id_t GetQueueID() const;
0097
0098   bool GetInfoItemByPathAsString(const char *path, SBStream &strm);
0099
0100   void StepOver(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
0101
0102   void StepOver(lldb::RunMode stop_other_threads, SBError &error);
0103
0104   void StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
0105
0106   void StepInto(const char *target_name,
0107                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
0108
0109   void StepInto(const char *target_name, uint32_t end_line, SBError &error,
0110                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
0111
0112   void StepOut();
0113
0114   void StepOut(SBError &error);
0115
0116   void StepOutOfFrame(SBFrame &frame);
0117
0118   void StepOutOfFrame(SBFrame &frame, SBError &error);
0119
0120   void StepInstruction(bool step_over);
0121
0122   void StepInstruction(bool step_over, SBError &error);
0123
0124   SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec,
0125                         uint32_t line);
0126
0127   SBError StepUsingScriptedThreadPlan(const char *script_class_name);
0128
0129   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
0130                                       bool resume_immediately);
0131
0132   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
0133                                       lldb::SBStructuredData &args_data,
0134                                       bool resume_immediately);
0135
0136   SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line);
0137
0138   void RunToAddress(lldb::addr_t addr);
0139
0140   void RunToAddress(lldb::addr_t addr, SBError &error);
0141
0142   SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value);
0143
0144   SBError UnwindInnermostExpression();
0145
0146   /// LLDB currently supports process centric debugging which means when any
0147   /// thread in a process stops, all other threads are stopped. The Suspend()
0148   /// call here tells our process to suspend a thread and not let it run when
0149   /// the other threads in a process are allowed to run. So when
0150   /// SBProcess::Continue() is called, any threads that aren't suspended will
0151   /// be allowed to run. If any of the SBThread functions for stepping are
0152   /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
0153   /// thread will not be allowed to run and these functions will simply return.
0154   ///
0155   /// Eventually we plan to add support for thread centric debugging where
0156   /// each thread is controlled individually and each thread would broadcast
0157   /// its state, but we haven't implemented this yet.
0158   ///
0159   /// Likewise the SBThread::Resume() call will again allow the thread to run
0160   /// when the process is continued.
0161   ///
0162   /// Suspend() and Resume() functions are not currently reference counted, if
0163   /// anyone has the need for them to be reference counted, please let us
0164   /// know.
0165   bool Suspend();
0166
0167   bool Suspend(SBError &error);
0168
0169   bool Resume();
0170
0171   bool Resume(SBError &error);
0172
0173   bool IsSuspended();
0174
0175   bool IsStopped();
0176
0177   uint32_t GetNumFrames();
0178
0179   lldb::SBFrame GetFrameAtIndex(uint32_t idx);
0180
0181   lldb::SBFrame GetSelectedFrame();
0182
0183   lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
0184
0185   static bool EventIsThreadEvent(const SBEvent &event);
0186
0187   static SBFrame GetStackFrameFromEvent(const SBEvent &event);
0188
0189   static SBThread GetThreadFromEvent(const SBEvent &event);
0190
0191   lldb::SBProcess GetProcess();
0192
0193   const lldb::SBThread &operator=(const lldb::SBThread &rhs);
0194
0195   bool operator==(const lldb::SBThread &rhs) const;
0196
0197   bool operator!=(const lldb::SBThread &rhs) const;
0198
0199   bool GetDescription(lldb::SBStream &description) const;
0200
0201   bool GetDescription(lldb::SBStream &description, bool stop_format) const;
0202
0203   /// Similar to \a GetDescription() but the format of the description can be
0204   /// configured via the \p format parameter. See
0205   /// https://lldb.llvm.org/use/formatting.html for more information on format
0206   /// strings.
0207   ///
0208   /// \param[in] format
0209   ///   The format to use for generating the description.
0210   ///
0211   /// \param[out] output
0212   ///   The stream where the description will be written to.
0213   ///
0214   /// \return
0215   ///   An error object with an error message in case of failures.
0216   SBError GetDescriptionWithFormat(const SBFormat &format, SBStream &output);
0217
0218   bool GetStatus(lldb::SBStream &status) const;
0219
0220   SBThread GetExtendedBacktraceThread(const char *type);
0221
0222   uint32_t GetExtendedBacktraceOriginatingIndexID();
0223
0224   SBValue GetCurrentException();
0225
0226   SBThread GetCurrentExceptionBacktrace();
0227
0228   bool SafeToCallFunctions();
0229
0230   SBValue GetSiginfo();
0231
0232 private:
0233   friend class SBBreakpoint;
0234   friend class SBBreakpointLocation;
0235   friend class SBBreakpointCallbackBaton;
0236   friend class SBSaveCoreOptions;
0237   friend class SBExecutionContext;
0238   friend class SBFrame;
0239   friend class SBProcess;
0240   friend class SBDebugger;
0241   friend class SBValue;
0242   friend class lldb_private::QueueImpl;
0243   friend class SBQueueItem;
0244   friend class SBThreadCollection;
0245   friend class SBThreadPlan;
0246   friend class SBTrace;
0247
0248   friend class lldb_private::python::SWIGBridge;
0249
0250   SBThread(const lldb::ThreadSP &lldb_object_sp);
0251
0252   void SetThread(const lldb::ThreadSP &lldb_object_sp);
0253
0254   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
0255                         lldb_private::ThreadPlan *new_plan);
0256
0257   lldb::ThreadSP GetSP() const;
0258
0259   lldb::ExecutionContextRefSP m_opaque_sp;
0260
0261   lldb_private::Thread *operator->();
0262
0263   lldb_private::Thread *get();
0264 };
0265
0266 } // namespace lldb
0267
0268 #endif // LLDB_API_SBTHREAD_H