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