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     //      NB. This is actually enforced underneath the breakpoint system, the Process plugin is expected to
  93     //      call BreakpointSite::IsValidForThread, and set the thread's StopInfo to "no reason".  That way,
  94     //      thread displays won't show stops for breakpoints not for that thread...
  95     //   b) If the ignore count says we shouldn't stop, then ditto.
  96     //   c) If the condition says we shouldn't stop, then ditto.
  97     //   d) Otherwise, the callback will get run, and if it returns true we will stop, and if false we won't.
  98     //  The asynchronous callback can run the target itself, but at present that should be the last action the
  99     //  callback does.  We will relax this condition at some point, but it will take a bit of plumbing to get
 100     //  that to work.
 101     //
 102     //------------------------------------------------------------------
 103
 104     //------------------------------------------------------------------
 105     /// Adds a callback to the breakpoint option set.
 106     ///
 107     /// @param[in] callback
 108     ///    The function to be called when the breakpoint gets hit.
 109     ///
 110     /// @param[in] baton_sp
 111     ///    A baton which will get passed back to the callback when it is invoked.
 112     ///
 113     /// @param[in] synchronous
 114     ///    Whether this is a synchronous or asynchronous callback.  See discussion above.
 115     //------------------------------------------------------------------
 116     void SetCallback (BreakpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous = false);
 117
 118
 119     //------------------------------------------------------------------
 120     /// Remove the callback from this option set.
 121     //------------------------------------------------------------------
 122     void ClearCallback ();
 123
 124     // The rest of these functions are meant to be used only within the breakpoint handling mechanism.
 125
 126     //------------------------------------------------------------------
 127     /// Use this function to invoke the callback for a specific stop.
 128     ///
 129     /// @param[in] context
 130     ///    The context in which the callback is to be invoked.  This includes the stop event, the
 131     ///    execution context of the stop (since you might hit the same breakpoint on multiple threads) and
 132     ///    whether we are currently executing synchronous or asynchronous callbacks.
 133     ///
 134     /// @param[in] break_id
 135     ///    The breakpoint ID that owns this option set.
 136     ///
 137     /// @param[in] break_loc_id
 138     ///    The breakpoint location ID that owns this option set.
 139     ///
 140     /// @return
 141     ///     The callback return value.
 142     //------------------------------------------------------------------
 143     bool InvokeCallback (StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
 144
 145     //------------------------------------------------------------------
 146     /// Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
 147     ///
 148     /// @return
 149     ///     The synchronicity of our callback.
 150     //------------------------------------------------------------------
 151     bool IsCallbackSynchronous () const
 152     {
 153         return m_callback_is_synchronous;
 154     }
 155
 156     //------------------------------------------------------------------
 157     /// Fetch the baton from the callback.
 158     ///
 159     /// @return
 160     ///     The baton.
 161     //------------------------------------------------------------------
 162     Baton *GetBaton ();
 163
 164     //------------------------------------------------------------------
 165     /// Fetch  a const version of the baton from the callback.
 166     ///
 167     /// @return
 168     ///     The baton.
 169     //------------------------------------------------------------------
 170     const Baton *GetBaton () const;
 171
 172     //------------------------------------------------------------------
 173     // Condition
 174     //------------------------------------------------------------------
 175     //------------------------------------------------------------------
 176     /// Set the breakpoint option's condition.
 177     ///
 178     /// @param[in] condition
 179     ///    The condition expression to evaluate when the breakpoint is hit.
 180     //------------------------------------------------------------------
 181     void SetCondition (const char *condition);
 182
 183     //------------------------------------------------------------------
 184     /// Return a pointer to the text of the condition expression.
 185     ///
 186     /// @return
 187     ///    A pointer to the condition expression text, or NULL if no
 188     //     condition has been set.
 189     //------------------------------------------------------------------
 190     const char *GetConditionText (size_t *hash = NULL) const;
 191
 192     //------------------------------------------------------------------
 193     // Enabled/Ignore Count
 194     //------------------------------------------------------------------
 195
 196     //------------------------------------------------------------------
 197     /// Check the Enable/Disable state.
 198     /// @return
 199     ///     \b true if the breakpoint is enabled, \b false if disabled.
 200     //------------------------------------------------------------------
 201     bool
 202     IsEnabled () const
 203     {
 204         return m_enabled;
 205     }
 206
 207     //------------------------------------------------------------------
 208     /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 209     //------------------------------------------------------------------
 210     void
 211     SetEnabled (bool enabled)
 212     {
 213         m_enabled = enabled;
 214     }
 215
 216     //------------------------------------------------------------------
 217     /// Check the One-shot state.
 218     /// @return
 219     ///     \b true if the breakpoint is one-shot, \b false otherwise.
 220     //------------------------------------------------------------------
 221     bool
 222     IsOneShot () const
 223     {
 224         return m_one_shot;
 225     }
 226
 227     //------------------------------------------------------------------
 228     /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 229     //------------------------------------------------------------------
 230     void
 231     SetOneShot (bool one_shot)
 232     {
 233         m_one_shot = one_shot;
 234     }
 235
 236     //------------------------------------------------------------------
 237     /// Set the breakpoint to ignore the next \a count breakpoint hits.
 238     /// @param[in] count
 239     ///    The number of breakpoint hits to ignore.
 240     //------------------------------------------------------------------
 241
 242     void
 243     SetIgnoreCount (uint32_t n)
 244     {
 245         m_ignore_count = n;
 246     }
 247
 248     //------------------------------------------------------------------
 249     /// Return the current Ignore Count.
 250     /// @return
 251     ///     The number of breakpoint hits to be ignored.
 252     //------------------------------------------------------------------
 253     uint32_t
 254     GetIgnoreCount () const
 255     {
 256         return m_ignore_count;
 257     }
 258
 259     //------------------------------------------------------------------
 260     /// Return the current thread spec for this option.  This will return NULL if the no thread
 261     /// specifications have been set for this Option yet.
 262     /// @return
 263     ///     The thread specification pointer for this option, or NULL if none has
 264     ///     been set yet.
 265     //------------------------------------------------------------------
 266     const ThreadSpec *
 267     GetThreadSpecNoCreate () const;
 268
 269     //------------------------------------------------------------------
 270     /// Returns a pointer to the ThreadSpec for this option, creating it.
 271     /// if it hasn't been created already.   This API is used for setting the
 272     /// ThreadSpec items for this option.
 273     //------------------------------------------------------------------
 274     ThreadSpec *
 275     GetThreadSpec ();
 276
 277     void
 278     SetThreadID(lldb::tid_t thread_id);
 279
 280     void
 281     GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 282
 283     //------------------------------------------------------------------
 284     /// Returns true if the breakpoint option has a callback set.
 285     //------------------------------------------------------------------
 286     bool
 287     HasCallback() const;
 288
 289     //------------------------------------------------------------------
 290     /// This is the default empty callback.
 291     /// @return
 292     ///     The thread id for which the breakpoint hit will stop,
 293     ///     LLDB_INVALID_THREAD_ID for all threads.
 294     //------------------------------------------------------------------
 295     static bool
 296     NullCallback (void *baton,
 297                   StoppointCallbackContext *context,
 298                   lldb::user_id_t break_id,
 299                   lldb::user_id_t break_loc_id);
 300
 301
 302     struct CommandData
 303     {
 304         CommandData () :
 305             user_source(),
 306             script_source(),
 307             stop_on_error(true)
 308         {
 309         }
 310
 311         ~CommandData ()
 312         {
 313         }
 314
 315         StringList user_source;
 316         std::string script_source;
 317         bool stop_on_error;
 318     };
 319
 320     class CommandBaton : public Baton
 321     {
 322     public:
 323         CommandBaton (CommandData *data) :
 324             Baton (data)
 325         {
 326         }
 327
 328         virtual
 329         ~CommandBaton ()
 330         {
 331             delete ((CommandData *)m_data);
 332             m_data = NULL;
 333         }
 334
 335         virtual void
 336         GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 337
 338     };
 339
 340 protected:
 341     //------------------------------------------------------------------
 342     // Classes that inherit from BreakpointOptions can see and modify these
 343     //------------------------------------------------------------------
 344
 345 private:
 346     //------------------------------------------------------------------
 347     // For BreakpointOptions only
 348     //------------------------------------------------------------------
 349     BreakpointHitCallback m_callback; // This is the callback function pointer
 350     lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
 351     bool m_callback_is_synchronous;
 352     bool m_enabled;
 353     bool m_one_shot;
 354     uint32_t m_ignore_count; // Number of times to ignore this breakpoint
 355     std::unique_ptr<ThreadSpec> m_thread_spec_ap; // Thread for which this breakpoint will take
 356     std::string m_condition_text;  // The condition to test.
 357     size_t m_condition_text_hash; // Its hash, so that locations know when the condition is updated.
 358 };
 359
 360 } // namespace lldb_private
 361
 362 #endif  // liblldb_BreakpointOptions_h_