LLDB  mainline
WatchpointOptions.h
Go to the documentation of this file.
1 //===-- WatchpointOptions.h -------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef liblldb_WatchpointOptions_h_
10 #define liblldb_WatchpointOptions_h_
11 
12 #include <memory>
13 #include <string>
14 
15 #include "lldb/Utility/Baton.h"
17 #include "lldb/lldb-private.h"
18 
19 namespace lldb_private {
20 
21 /// \class WatchpointOptions WatchpointOptions.h
22 /// "lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a
23 /// watchpoint.
24 
26 public:
27  // Constructors and Destructors
28  /// Default constructor. The watchpoint is enabled, and has no condition,
29  /// callback, ignore count, etc...
32 
34  /// This constructor allows you to specify all the watchpoint options.
35  ///
36  /// \param[in] callback
37  /// This is the plugin for some code that gets run, returns \b true if we
38  /// are to stop.
39  ///
40  /// \param[in] baton
41  /// Client data that will get passed to the callback.
42  ///
43  /// \param[in] thread_id
44  /// Only stop if \a thread_id hits the watchpoint.
45  WatchpointOptions(WatchpointHitCallback callback, void *baton,
47 
48  virtual ~WatchpointOptions();
49 
50  // Operators
52 
53  // Callbacks
54  //
55  // Watchpoint callbacks come in two forms, synchronous and asynchronous.
56  // Synchronous callbacks will get run before any of the thread plans are
57  // consulted, and if they return false the target will continue "under the
58  // radar" of the thread plans. There are a couple of restrictions to
59  // synchronous callbacks: 1) They should NOT resume the target themselves.
60  // Just return false if you want the target to restart. 2) Watchpoints with
61  // synchronous callbacks can't have conditions (or rather, they can have
62  // them, but they
63  // won't do anything. Ditto with ignore counts, etc... You are supposed
64  // to control that all through the
65  // callback.
66  // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
67  // thread plan. The logic there is:
68  // a) If the watchpoint is thread specific and not for this thread, continue
69  // w/o running the callback.
70  // b) If the ignore count says we shouldn't stop, then ditto.
71  // c) If the condition says we shouldn't stop, then ditto.
72  // d) Otherwise, the callback will get run, and if it returns true we will
73  // stop, and if false we won't.
74  // The asynchronous callback can run the target itself, but at present that
75  // should be the last action the
76  // callback does. We will relax this condition at some point, but it will
77  // take a bit of plumbing to get
78  // that to work.
79  //
80 
81  /// Adds a callback to the watchpoint option set.
82  ///
83  /// \param[in] callback
84  /// The function to be called when the watchpoint gets hit.
85  ///
86  /// \param[in] baton_sp
87  /// A baton which will get passed back to the callback when it is invoked.
88  ///
89  /// \param[in] synchronous
90  /// Whether this is a synchronous or asynchronous callback. See discussion
91  /// above.
92  void SetCallback(WatchpointHitCallback callback,
93  const lldb::BatonSP &baton_sp, bool synchronous = false);
94 
95  /// Remove the callback from this option set.
96  void ClearCallback();
97 
98  // The rest of these functions are meant to be used only within the
99  // watchpoint handling mechanism.
100 
101  /// Use this function to invoke the callback for a specific stop.
102  ///
103  /// \param[in] context
104  /// The context in which the callback is to be invoked. This includes the
105  /// stop event, the
106  /// execution context of the stop (since you might hit the same watchpoint
107  /// on multiple threads) and
108  /// whether we are currently executing synchronous or asynchronous
109  /// callbacks.
110  ///
111  /// \param[in] watch_id
112  /// The watchpoint ID that owns this option set.
113  ///
114  /// \return
115  /// The callback return value.
117  lldb::user_id_t watch_id);
118 
119  /// Used in InvokeCallback to tell whether it is the right time to run this
120  /// kind of callback.
121  ///
122  /// \return
123  /// The synchronicity of our callback.
124  bool IsCallbackSynchronous() { return m_callback_is_synchronous; }
125 
126  /// Fetch the baton from the callback.
127  ///
128  /// \return
129  /// The baton.
130  Baton *GetBaton();
131 
132  /// Fetch a const version of the baton from the callback.
133  ///
134  /// \return
135  /// The baton.
136  const Baton *GetBaton() const;
137 
138  /// Return the current thread spec for this option. This will return nullptr
139  /// if the no thread specifications have been set for this Option yet.
140  /// \return
141  /// The thread specification pointer for this option, or nullptr if none
142  /// has
143  /// been set yet.
144  const ThreadSpec *GetThreadSpecNoCreate() const;
145 
146  /// Returns a pointer to the ThreadSpec for this option, creating it. if it
147  /// hasn't been created already. This API is used for setting the
148  /// ThreadSpec items for this option.
150 
151  void SetThreadID(lldb::tid_t thread_id);
152 
153  void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
154 
155  /// Get description for callback only.
157 
158  /// Returns true if the watchpoint option has a callback set.
159  bool HasCallback();
160 
161  /// This is the default empty callback.
162  /// \return
163  /// The thread id for which the watchpoint hit will stop,
164  /// LLDB_INVALID_THREAD_ID for all threads.
165  static bool NullCallback(void *baton, StoppointCallbackContext *context,
166  lldb::user_id_t watch_id);
167 
168  struct CommandData {
170 
171  ~CommandData() = default;
172 
174  std::string script_source;
176  };
177 
178  class CommandBaton : public TypedBaton<CommandData> {
179  public:
180  CommandBaton(std::unique_ptr<CommandData> Data)
181  : TypedBaton(std::move(Data)) {}
182 
183  void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
184  };
185 
186 protected:
187  // Classes that inherit from WatchpointOptions can see and modify these
188 
189 private:
190  // For WatchpointOptions only
191  WatchpointHitCallback m_callback; // This is the callback function pointer
192  lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
193  bool m_callback_is_synchronous;
194  std::unique_ptr<ThreadSpec>
195  m_thread_spec_up; // Thread for which this watchpoint will take
196 };
197 
198 } // namespace lldb_private
199 
200 #endif // liblldb_WatchpointOptions_h_
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
void SetThreadID(lldb::tid_t thread_id)
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
static WatchpointOptions * CopyOptionsNoCallback(WatchpointOptions &rhs)
void GetCallbackDescription(Stream *s, lldb::DescriptionLevel level) const
Get description for callback only.
uint64_t user_id_t
Definition: lldb-types.h:84
void GetDescription(Stream *s, lldb::DescriptionLevel level) const
static bool NullCallback(void *baton, StoppointCallbackContext *context, lldb::user_id_t watch_id)
This is the default empty callback.
void ClearCallback()
Remove the callback from this option set.
uint64_t tid_t
Definition: lldb-types.h:86
ThreadSpec * GetThreadSpec()
Returns a pointer to the ThreadSpec for this option, creating it.
bool HasCallback()
Returns true if the watchpoint option has a callback set.
void SetCallback(WatchpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous=false)
Adds a callback to the watchpoint option set.
Baton * GetBaton()
Fetch the baton from the callback.
bool InvokeCallback(StoppointCallbackContext *context, lldb::user_id_t watch_id)
Use this function to invoke the callback for a specific stop.
bool IsCallbackSynchronous()
Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
WatchpointOptions()
Default constructor.
"lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a watchpoint.
#define LLDB_INVALID_THREAD_ID
Definition: lldb-defines.h:93
const WatchpointOptions & operator=(const WatchpointOptions &rhs)
const ThreadSpec * GetThreadSpecNoCreate() const
Return the current thread spec for this option.
A class designed to wrap callback batons so they can cleanup any acquired resources.
Definition: Baton.h:33
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
CommandBaton(std::unique_ptr< CommandData > Data)