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