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