contrib/llvm/tools/lldb/include/lldb/Breakpoint/BreakpointOptions.h

   1 //===-- BreakpointOptions.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_BreakpointOptions_h_
  11 #define liblldb_BreakpointOptions_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 BreakpointOptions BreakpointOptions.h "lldb/Breakpoint/BreakpointOptions.h"
  25 /// @brief Class that manages the options on a breakpoint or breakpoint location.
  26 //----------------------------------------------------------------------
  27
  28 class BreakpointOptions
  29 {
  30 public:
  31     //------------------------------------------------------------------
  32     // Constructors and Destructors
  33     //------------------------------------------------------------------
  34     //------------------------------------------------------------------
  35     /// Default constructor.  The breakpoint is enabled, and has no condition,
  36     /// callback, ignore count, etc...
  37     //------------------------------------------------------------------
  38     BreakpointOptions();
  39     BreakpointOptions(const BreakpointOptions& rhs);
  40
  41     static BreakpointOptions *
  42     CopyOptionsNoCallback (BreakpointOptions &rhs);
  43     //------------------------------------------------------------------
  44     /// This constructor allows you to specify all the breakpoint options.
  45     ///
  46     /// @param[in] condition
  47     ///    The expression which if it evaluates to \b true if we are to stop
  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] enabled
  56     ///    Is this breakpoint enabled.
  57     ///
  58     /// @param[in] ignore
  59     ///    How many breakpoint hits we should ignore before stopping.
  60     ///
  61     /// @param[in] thread_id
  62     ///    Only stop if \a thread_id hits the breakpoint.
  63     //------------------------------------------------------------------
  64     BreakpointOptions(void *condition,
  65                       BreakpointHitCallback callback,
  66                       void *baton,
  67                       bool enabled = true,
  68                       int32_t ignore = 0,
  69                       lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID,
  70                       bool one_shot = false);
  71
  72     virtual ~BreakpointOptions();
  73
  74     //------------------------------------------------------------------
  75     // Operators
  76     //------------------------------------------------------------------
  77     const BreakpointOptions&
  78     operator=(const BreakpointOptions& rhs);
  79
  80     //------------------------------------------------------------------
  81     // Callbacks
  82     //
  83     // Breakpoint callbacks come in two forms, synchronous and asynchronous.  Synchronous callbacks will get
  84     // run before any of the thread plans are consulted, and if they return false the target will continue
  85     // "under the radar" of the thread plans.  There are a couple of restrictions to synchronous callbacks:
  86     // 1) They should NOT resume the target themselves.  Just return false if you want the target to restart.
  87     // 2) Breakpoints with synchronous callbacks can't have conditions (or rather, they can have them, but they
  88     //    won't do anything.  Ditto with ignore counts, etc...  You are supposed to control that all through the
  89     //    callback.
  90     // Asynchronous callbacks get run as part of the "ShouldStop" logic in the thread plan.  The logic there is:
  91     //   a) If the breakpoint is thread specific and not for this thread, continue w/o running the callback.
  92     //   b) If the ignore count says we shouldn't stop, then ditto.
  93     //   c) If the condition says we shouldn't stop, then ditto.
  94     //   d) Otherwise, the callback will get run, and if it returns true we will stop, and if false we won't.
  95     //  The asynchronous callback can run the target itself, but at present that should be the last action the
  96     //  callback does.  We will relax this condition at some point, but it will take a bit of plumbing to get
  97     //  that to work.
  98     //
  99     //------------------------------------------------------------------
 100
 101     //------------------------------------------------------------------
 102     /// Adds a callback to the breakpoint option set.
 103     ///
 104     /// @param[in] callback
 105     ///    The function to be called when the breakpoint gets hit.
 106     ///
 107     /// @param[in] baton_sp
 108     ///    A baton which will get passed back to the callback when it is invoked.
 109     ///
 110     /// @param[in] synchronous
 111     ///    Whether this is a synchronous or asynchronous callback.  See discussion above.
 112     //------------------------------------------------------------------
 113     void SetCallback (BreakpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous = false);
 114
 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 breakpoint handling mechanism.
 122
 123     //------------------------------------------------------------------
 124     /// Use this function to invoke the callback for a specific stop.
 125     ///
 126     /// @param[in] context
 127     ///    The context in which the callback is to be invoked.  This includes the stop event, the
 128     ///    execution context of the stop (since you might hit the same breakpoint on multiple threads) and
 129     ///    whether we are currently executing synchronous or asynchronous callbacks.
 130     ///
 131     /// @param[in] break_id
 132     ///    The breakpoint ID that owns this option set.
 133     ///
 134     /// @param[in] break_loc_id
 135     ///    The breakpoint location ID that owns this option set.
 136     ///
 137     /// @return
 138     ///     The callback return value.
 139     //------------------------------------------------------------------
 140     bool InvokeCallback (StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
 141
 142     //------------------------------------------------------------------
 143     /// Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
 144     ///
 145     /// @return
 146     ///     The synchronicity of our callback.
 147     //------------------------------------------------------------------
 148     bool IsCallbackSynchronous () {
 149         return m_callback_is_synchronous;
 150     }
 151
 152     //------------------------------------------------------------------
 153     /// Fetch the baton from the callback.
 154     ///
 155     /// @return
 156     ///     The baton.
 157     //------------------------------------------------------------------
 158     Baton *GetBaton ();
 159
 160     //------------------------------------------------------------------
 161     /// Fetch  a const version of the baton from the callback.
 162     ///
 163     /// @return
 164     ///     The baton.
 165     //------------------------------------------------------------------
 166     const Baton *GetBaton () const;
 167
 168     //------------------------------------------------------------------
 169     // Condition
 170     //------------------------------------------------------------------
 171     //------------------------------------------------------------------
 172     /// Set the breakpoint option's condition.
 173     ///
 174     /// @param[in] condition
 175     ///    The condition expression to evaluate when the breakpoint is hit.
 176     //------------------------------------------------------------------
 177     void SetCondition (const char *condition);
 178
 179     //------------------------------------------------------------------
 180     /// Return a pointer to the text of the condition expression.
 181     ///
 182     /// @return
 183     ///    A pointer to the condition expression text, or NULL if no
 184     //     condition has been set.
 185     //------------------------------------------------------------------
 186     const char *GetConditionText (size_t *hash = NULL) const;
 187
 188     //------------------------------------------------------------------
 189     // Enabled/Ignore Count
 190     //------------------------------------------------------------------
 191
 192     //------------------------------------------------------------------
 193     /// Check the Enable/Disable state.
 194     /// @return
 195     ///     \b true if the breakpoint is enabled, \b false if disabled.
 196     //------------------------------------------------------------------
 197     bool
 198     IsEnabled () const
 199     {
 200         return m_enabled;
 201     }
 202
 203     //------------------------------------------------------------------
 204     /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 205     //------------------------------------------------------------------
 206     void
 207     SetEnabled (bool enabled)
 208     {
 209         m_enabled = enabled;
 210     }
 211
 212     //------------------------------------------------------------------
 213     /// Check the One-shot state.
 214     /// @return
 215     ///     \b true if the breakpoint is one-shot, \b false otherwise.
 216     //------------------------------------------------------------------
 217     bool
 218     IsOneShot () const
 219     {
 220         return m_one_shot;
 221     }
 222
 223     //------------------------------------------------------------------
 224     /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 225     //------------------------------------------------------------------
 226     void
 227     SetOneShot (bool one_shot)
 228     {
 229         m_one_shot = one_shot;
 230     }
 231
 232     //------------------------------------------------------------------
 233     /// Set the breakpoint to ignore the next \a count breakpoint hits.
 234     /// @param[in] count
 235     ///    The number of breakpoint hits to ignore.
 236     //------------------------------------------------------------------
 237
 238     void
 239     SetIgnoreCount (uint32_t n)
 240     {
 241         m_ignore_count = n;
 242     }
 243
 244     //------------------------------------------------------------------
 245     /// Return the current Ignore Count.
 246     /// @return
 247     ///     The number of breakpoint hits to be ignored.
 248     //------------------------------------------------------------------
 249     uint32_t
 250     GetIgnoreCount () const
 251     {
 252         return m_ignore_count;
 253     }
 254
 255     //------------------------------------------------------------------
 256     /// Return the current thread spec for this option.  This will return NULL if the no thread
 257     /// specifications have been set for this Option yet.
 258     /// @return
 259     ///     The thread specification pointer for this option, or NULL if none has
 260     ///     been set yet.
 261     //------------------------------------------------------------------
 262     const ThreadSpec *
 263     GetThreadSpecNoCreate () const;
 264
 265     //------------------------------------------------------------------
 266     /// Returns a pointer to the ThreadSpec for this option, creating it.
 267     /// if it hasn't been created already.   This API is used for setting the
 268     /// ThreadSpec items for this option.
 269     //------------------------------------------------------------------
 270     ThreadSpec *
 271     GetThreadSpec ();
 272
 273     void
 274     SetThreadID(lldb::tid_t thread_id);
 275
 276     void
 277     GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 278
 279     //------------------------------------------------------------------
 280     /// Returns true if the breakpoint option has a callback set.
 281     //------------------------------------------------------------------
 282     bool
 283     HasCallback();
 284
 285     //------------------------------------------------------------------
 286     /// This is the default empty callback.
 287     /// @return
 288     ///     The thread id for which the breakpoint hit will stop,
 289     ///     LLDB_INVALID_THREAD_ID for all threads.
 290     //------------------------------------------------------------------
 291     static bool
 292     NullCallback (void *baton,
 293                   StoppointCallbackContext *context,
 294                   lldb::user_id_t break_id,
 295                   lldb::user_id_t break_loc_id);
 296
 297
 298     struct CommandData
 299     {
 300         CommandData () :
 301             user_source(),
 302             script_source(),
 303             stop_on_error(true)
 304         {
 305         }
 306
 307         ~CommandData ()
 308         {
 309         }
 310
 311         StringList user_source;
 312         std::string script_source;
 313         bool stop_on_error;
 314     };
 315
 316     class CommandBaton : public Baton
 317     {
 318     public:
 319         CommandBaton (CommandData *data) :
 320             Baton (data)
 321         {
 322         }
 323
 324         virtual
 325         ~CommandBaton ()
 326         {
 327             delete ((CommandData *)m_data);
 328             m_data = NULL;
 329         }
 330
 331         virtual void
 332         GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 333
 334     };
 335
 336 protected:
 337     //------------------------------------------------------------------
 338     // Classes that inherit from BreakpointOptions can see and modify these
 339     //------------------------------------------------------------------
 340
 341 private:
 342     //------------------------------------------------------------------
 343     // For BreakpointOptions only
 344     //------------------------------------------------------------------
 345     BreakpointHitCallback m_callback; // This is the callback function pointer
 346     lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
 347     bool m_callback_is_synchronous;
 348     bool m_enabled;
 349     bool m_one_shot;
 350     uint32_t m_ignore_count; // Number of times to ignore this breakpoint
 351     std::unique_ptr<ThreadSpec> m_thread_spec_ap; // Thread for which this breakpoint will take
 352     std::string m_condition_text;  // The condition to test.
 353     size_t m_condition_text_hash; // Its hash, so that locations know when the condition is updated.
 354 };
 355
 356 } // namespace lldb_private
 357
 358 #endif  // liblldb_BreakpointOptions_h_