contrib/llvm-project/lldb/include/lldb/API/SBThread.h

   1 //===-- SBThread.h ----------------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef LLDB_SBThread_h_
  10 #define LLDB_SBThread_h_
  11
  12 #include "lldb/API/SBDefines.h"
  13
  14 #include <stdio.h>
  15
  16 namespace lldb {
  17
  18 class SBFrame;
  19
  20 class LLDB_API SBThread {
  21 public:
  22   enum {
  23     eBroadcastBitStackChanged = (1 << 0),
  24     eBroadcastBitThreadSuspended = (1 << 1),
  25     eBroadcastBitThreadResumed = (1 << 2),
  26     eBroadcastBitSelectedFrameChanged = (1 << 3),
  27     eBroadcastBitThreadSelected = (1 << 4)
  28   };
  29
  30   static const char *GetBroadcasterClassName();
  31
  32   SBThread();
  33
  34   SBThread(const lldb::SBThread &thread);
  35
  36   SBThread(const lldb::ThreadSP &lldb_object_sp);
  37
  38   ~SBThread();
  39
  40   lldb::SBQueue GetQueue() const;
  41
  42   explicit operator bool() const;
  43
  44   bool IsValid() const;
  45
  46   void Clear();
  47
  48   lldb::StopReason GetStopReason();
  49
  50   /// Get the number of words associated with the stop reason.
  51   /// See also GetStopReasonDataAtIndex().
  52   size_t GetStopReasonDataCount();
  53
  54   /// Get information associated with a stop reason.
  55   ///
  56   /// Breakpoint stop reasons will have data that consists of pairs of
  57   /// breakpoint IDs followed by the breakpoint location IDs (they always come
  58   /// in pairs).
  59   ///
  60   /// Stop Reason              Count Data Type
  61   /// ======================== ===== =========================================
  62   /// eStopReasonNone          0
  63   /// eStopReasonTrace         0
  64   /// eStopReasonBreakpoint    N     duple: {breakpoint id, location id}
  65   /// eStopReasonWatchpoint    1     watchpoint id
  66   /// eStopReasonSignal        1     unix signal number
  67   /// eStopReasonException     N     exception data
  68   /// eStopReasonExec          0
  69   /// eStopReasonPlanComplete  0
  70   uint64_t GetStopReasonDataAtIndex(uint32_t idx);
  71
  72   bool GetStopReasonExtendedInfoAsJSON(lldb::SBStream &stream);
  73
  74   SBThreadCollection
  75   GetStopReasonExtendedBacktraces(InstrumentationRuntimeType type);
  76
  77   size_t GetStopDescription(char *dst, size_t dst_len);
  78
  79   SBValue GetStopReturnValue();
  80
  81   lldb::tid_t GetThreadID() const;
  82
  83   uint32_t GetIndexID() const;
  84
  85   const char *GetName() const;
  86
  87   const char *GetQueueName() const;
  88
  89   lldb::queue_id_t GetQueueID() const;
  90
  91   bool GetInfoItemByPathAsString(const char *path, SBStream &strm);
  92
  93   void StepOver(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
  94
  95   void StepOver(lldb::RunMode stop_other_threads, SBError &error);
  96
  97   void StepInto(lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
  98
  99   void StepInto(const char *target_name,
 100                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
 101
 102   void StepInto(const char *target_name, uint32_t end_line, SBError &error,
 103                 lldb::RunMode stop_other_threads = lldb::eOnlyDuringStepping);
 104
 105   void StepOut();
 106
 107   void StepOut(SBError &error);
 108
 109   void StepOutOfFrame(SBFrame &frame);
 110
 111   void StepOutOfFrame(SBFrame &frame, SBError &error);
 112
 113   void StepInstruction(bool step_over);
 114
 115   void StepInstruction(bool step_over, SBError &error);
 116
 117   SBError StepOverUntil(lldb::SBFrame &frame, lldb::SBFileSpec &file_spec,
 118                         uint32_t line);
 119
 120   SBError StepUsingScriptedThreadPlan(const char *script_class_name);
 121
 122   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
 123                                       bool resume_immediately);
 124
 125   SBError StepUsingScriptedThreadPlan(const char *script_class_name,
 126                                       lldb::SBStructuredData &args_data,
 127                                       bool resume_immediately);
 128
 129   SBError JumpToLine(lldb::SBFileSpec &file_spec, uint32_t line);
 130
 131   void RunToAddress(lldb::addr_t addr);
 132
 133   void RunToAddress(lldb::addr_t addr, SBError &error);
 134
 135   SBError ReturnFromFrame(SBFrame &frame, SBValue &return_value);
 136
 137   SBError UnwindInnermostExpression();
 138
 139   /// LLDB currently supports process centric debugging which means when any
 140   /// thread in a process stops, all other threads are stopped. The Suspend()
 141   /// call here tells our process to suspend a thread and not let it run when
 142   /// the other threads in a process are allowed to run. So when
 143   /// SBProcess::Continue() is called, any threads that aren't suspended will
 144   /// be allowed to run. If any of the SBThread functions for stepping are
 145   /// called (StepOver, StepInto, StepOut, StepInstruction, RunToAddress), the
 146   /// thread will not be allowed to run and these functions will simply return.
 147   ///
 148   /// Eventually we plan to add support for thread centric debugging where
 149   /// each thread is controlled individually and each thread would broadcast
 150   /// its state, but we haven't implemented this yet.
 151   ///
 152   /// Likewise the SBThread::Resume() call will again allow the thread to run
 153   /// when the process is continued.
 154   ///
 155   /// Suspend() and Resume() functions are not currently reference counted, if
 156   /// anyone has the need for them to be reference counted, please let us
 157   /// know.
 158   bool Suspend();
 159
 160   bool Suspend(SBError &error);
 161
 162   bool Resume();
 163
 164   bool Resume(SBError &error);
 165
 166   bool IsSuspended();
 167
 168   bool IsStopped();
 169
 170   uint32_t GetNumFrames();
 171
 172   lldb::SBFrame GetFrameAtIndex(uint32_t idx);
 173
 174   lldb::SBFrame GetSelectedFrame();
 175
 176   lldb::SBFrame SetSelectedFrame(uint32_t frame_idx);
 177
 178   static bool EventIsThreadEvent(const SBEvent &event);
 179
 180   static SBFrame GetStackFrameFromEvent(const SBEvent &event);
 181
 182   static SBThread GetThreadFromEvent(const SBEvent &event);
 183
 184   lldb::SBProcess GetProcess();
 185
 186   const lldb::SBThread &operator=(const lldb::SBThread &rhs);
 187
 188   bool operator==(const lldb::SBThread &rhs) const;
 189
 190   bool operator!=(const lldb::SBThread &rhs) const;
 191
 192   bool GetDescription(lldb::SBStream &description) const;
 193
 194   bool GetDescription(lldb::SBStream &description, bool stop_format) const;
 195
 196   bool GetStatus(lldb::SBStream &status) const;
 197
 198   SBThread GetExtendedBacktraceThread(const char *type);
 199
 200   uint32_t GetExtendedBacktraceOriginatingIndexID();
 201
 202   SBValue GetCurrentException();
 203
 204   SBThread GetCurrentExceptionBacktrace();
 205
 206   bool SafeToCallFunctions();
 207
 208 private:
 209   friend class SBBreakpoint;
 210   friend class SBBreakpointLocation;
 211   friend class SBBreakpointCallbackBaton;
 212   friend class SBExecutionContext;
 213   friend class SBFrame;
 214   friend class SBProcess;
 215   friend class SBDebugger;
 216   friend class SBValue;
 217   friend class lldb_private::QueueImpl;
 218   friend class SBQueueItem;
 219   friend class SBThreadPlan;
 220
 221   void SetThread(const lldb::ThreadSP &lldb_object_sp);
 222
 223   SBError ResumeNewPlan(lldb_private::ExecutionContext &exe_ctx,
 224                         lldb_private::ThreadPlan *new_plan);
 225
 226   lldb::ExecutionContextRefSP m_opaque_sp;
 227
 228   lldb_private::Thread *operator->();
 229
 230   lldb_private::Thread *get();
 231 };
 232
 233 } // namespace lldb
 234
 235 #endif // LLDB_SBThread_h_