include/lldb/Breakpoint/WatchpointOptions.h

   1 //===-- WatchpointOptions.h -------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_WatchpointOptions_h_
  11 #define liblldb_WatchpointOptions_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <memory>
  16 #include <string>
  17
  18 // Other libraries and framework includes
  19 // Project includes
  20 #include "lldb/Utility/Baton.h"
  21 #include "lldb/Utility/StringList.h"
  22 #include "lldb/lldb-private.h"
  23
  24 namespace lldb_private {
  25
  26 //----------------------------------------------------------------------
  27 /// @class WatchpointOptions WatchpointOptions.h
  28 /// "lldb/Breakpoint/WatchpointOptions.h"
  29 /// @brief Class that manages the options on a watchpoint.
  30 //----------------------------------------------------------------------
  31
  32 class WatchpointOptions {
  33 public:
  34   //------------------------------------------------------------------
  35   // Constructors and Destructors
  36   //------------------------------------------------------------------
  37   //------------------------------------------------------------------
  38   /// Default constructor.  The watchpoint is enabled, and has no condition,
  39   /// callback, ignore count, etc...
  40   //------------------------------------------------------------------
  41   WatchpointOptions();
  42   WatchpointOptions(const WatchpointOptions &rhs);
  43
  44   static WatchpointOptions *CopyOptionsNoCallback(WatchpointOptions &rhs);
  45   //------------------------------------------------------------------
  46   /// This constructor allows you to specify all the watchpoint options.
  47   ///
  48   /// @param[in] callback
  49   ///    This is the plugin for some code that gets run, returns \b true if we
  50   ///    are to stop.
  51   ///
  52   /// @param[in] baton
  53   ///    Client data that will get passed to the callback.
  54   ///
  55   /// @param[in] thread_id
  56   ///    Only stop if \a thread_id hits the watchpoint.
  57   //------------------------------------------------------------------
  58   WatchpointOptions(WatchpointHitCallback callback, void *baton,
  59                     lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
  60
  61   virtual ~WatchpointOptions();
  62
  63   //------------------------------------------------------------------
  64   // Operators
  65   //------------------------------------------------------------------
  66   const WatchpointOptions &operator=(const WatchpointOptions &rhs);
  67
  68   //------------------------------------------------------------------
  69   // Callbacks
  70   //
  71   // Watchpoint callbacks come in two forms, synchronous and asynchronous.
  72   // Synchronous callbacks will get
  73   // run before any of the thread plans are consulted, and if they return false
  74   // the target will continue
  75   // "under the radar" of the thread plans.  There are a couple of restrictions
  76   // to synchronous callbacks:
  77   // 1) They should NOT resume the target themselves.  Just return false if you
  78   // want the target to restart.
  79   // 2) Watchpoints with synchronous callbacks can't have conditions (or rather,
  80   // they can have them, but they
  81   //    won't do anything.  Ditto with ignore counts, etc...  You are supposed
  82   //    to control that all through the
  83   //    callback.
  84   // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
  85   // thread plan.  The logic there is:
  86   //   a) If the watchpoint is thread specific and not for this thread, continue
  87   //   w/o running the callback.
  88   //   b) If the ignore count says we shouldn't stop, then ditto.
  89   //   c) If the condition says we shouldn't stop, then ditto.
  90   //   d) Otherwise, the callback will get run, and if it returns true we will
  91   //   stop, and if false we won't.
  92   //  The asynchronous callback can run the target itself, but at present that
  93   //  should be the last action the
  94   //  callback does.  We will relax this condition at some point, but it will
  95   //  take a bit of plumbing to get
  96   //  that to work.
  97   //
  98   //------------------------------------------------------------------
  99
 100   //------------------------------------------------------------------
 101   /// Adds a callback to the watchpoint option set.
 102   ///
 103   /// @param[in] callback
 104   ///    The function to be called when the watchpoint gets hit.
 105   ///
 106   /// @param[in] baton_sp
 107   ///    A baton which will get passed back to the callback when it is invoked.
 108   ///
 109   /// @param[in] synchronous
 110   ///    Whether this is a synchronous or asynchronous callback.  See discussion
 111   ///    above.
 112   //------------------------------------------------------------------
 113   void SetCallback(WatchpointHitCallback callback,
 114                    const lldb::BatonSP &baton_sp, bool synchronous = false);
 115
 116   //------------------------------------------------------------------
 117   /// Remove the callback from this option set.
 118   //------------------------------------------------------------------
 119   void ClearCallback();
 120
 121   // The rest of these functions are meant to be used only within the watchpoint
 122   // handling mechanism.
 123
 124   //------------------------------------------------------------------
 125   /// Use this function to invoke the callback for a specific stop.
 126   ///
 127   /// @param[in] context
 128   ///    The context in which the callback is to be invoked.  This includes the
 129   ///    stop event, the
 130   ///    execution context of the stop (since you might hit the same watchpoint
 131   ///    on multiple threads) and
 132   ///    whether we are currently executing synchronous or asynchronous
 133   ///    callbacks.
 134   ///
 135   /// @param[in] watch_id
 136   ///    The watchpoint ID that owns this option set.
 137   ///
 138   /// @return
 139   ///     The callback return value.
 140   //------------------------------------------------------------------
 141   bool InvokeCallback(StoppointCallbackContext *context,
 142                       lldb::user_id_t watch_id);
 143
 144   //------------------------------------------------------------------
 145   /// Used in InvokeCallback to tell whether it is the right time to run this
 146   /// kind of callback.
 147   ///
 148   /// @return
 149   ///     The synchronicity of our callback.
 150   //------------------------------------------------------------------
 151   bool IsCallbackSynchronous() { return m_callback_is_synchronous; }
 152
 153   //------------------------------------------------------------------
 154   /// Fetch the baton from the callback.
 155   ///
 156   /// @return
 157   ///     The baton.
 158   //------------------------------------------------------------------
 159   Baton *GetBaton();
 160
 161   //------------------------------------------------------------------
 162   /// Fetch  a const version of the baton from the callback.
 163   ///
 164   /// @return
 165   ///     The baton.
 166   //------------------------------------------------------------------
 167   const Baton *GetBaton() const;
 168
 169   //------------------------------------------------------------------
 170   /// Return the current thread spec for this option. This will return nullptr
 171   /// if the no thread
 172   /// specifications have been set for this Option yet.
 173   /// @return
 174   ///     The thread specification pointer for this option, or nullptr if none
 175   ///     has
 176   ///     been set yet.
 177   //------------------------------------------------------------------
 178   const ThreadSpec *GetThreadSpecNoCreate() const;
 179
 180   //------------------------------------------------------------------
 181   /// Returns a pointer to the ThreadSpec for this option, creating it.
 182   /// if it hasn't been created already.   This API is used for setting the
 183   /// ThreadSpec items for this option.
 184   //------------------------------------------------------------------
 185   ThreadSpec *GetThreadSpec();
 186
 187   void SetThreadID(lldb::tid_t thread_id);
 188
 189   void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
 190
 191   //------------------------------------------------------------------
 192   /// Get description for callback only.
 193   //------------------------------------------------------------------
 194   void GetCallbackDescription(Stream *s, lldb::DescriptionLevel level) const;
 195
 196   //------------------------------------------------------------------
 197   /// Returns true if the watchpoint option has a callback set.
 198   //------------------------------------------------------------------
 199   bool HasCallback();
 200
 201   //------------------------------------------------------------------
 202   /// This is the default empty callback.
 203   /// @return
 204   ///     The thread id for which the watchpoint hit will stop,
 205   ///     LLDB_INVALID_THREAD_ID for all threads.
 206   //------------------------------------------------------------------
 207   static bool NullCallback(void *baton, StoppointCallbackContext *context,
 208                            lldb::user_id_t watch_id);
 209
 210   struct CommandData {
 211     CommandData() : user_source(), script_source(), stop_on_error(true) {}
 212
 213     ~CommandData() = default;
 214
 215     StringList user_source;
 216     std::string script_source;
 217     bool stop_on_error;
 218   };
 219
 220   class CommandBaton : public TypedBaton<CommandData> {
 221   public:
 222     CommandBaton(std::unique_ptr<CommandData> Data)
 223         : TypedBaton(std::move(Data)) {}
 224
 225     void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
 226   };
 227
 228 protected:
 229   //------------------------------------------------------------------
 230   // Classes that inherit from WatchpointOptions can see and modify these
 231   //------------------------------------------------------------------
 232
 233 private:
 234   //------------------------------------------------------------------
 235   // For WatchpointOptions only
 236   //------------------------------------------------------------------
 237   WatchpointHitCallback m_callback;  // This is the callback function pointer
 238   lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
 239   bool m_callback_is_synchronous;
 240   std::unique_ptr<ThreadSpec>
 241       m_thread_spec_ap; // Thread for which this watchpoint will take
 242 };
 243
 244 } // namespace lldb_private
 245
 246 #endif // liblldb_WatchpointOptions_h_