1 //===-- WatchpointOptions.h -------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_WatchpointOptions_h_
11 #define liblldb_WatchpointOptions_h_
18 // Other libraries and framework includes
20 #include "lldb/Utility/Baton.h"
21 #include "lldb/Utility/StringList.h"
22 #include "lldb/lldb-private.h"
24 namespace lldb_private {
26 //----------------------------------------------------------------------
27 /// @class WatchpointOptions WatchpointOptions.h
28 /// "lldb/Breakpoint/WatchpointOptions.h"
29 /// @brief Class that manages the options on a watchpoint.
30 //----------------------------------------------------------------------
32 class WatchpointOptions {
34 //------------------------------------------------------------------
35 // Constructors and Destructors
36 //------------------------------------------------------------------
37 //------------------------------------------------------------------
38 /// Default constructor. The watchpoint is enabled, and has no condition,
39 /// callback, ignore count, etc...
40 //------------------------------------------------------------------
42 WatchpointOptions(const WatchpointOptions &rhs);
44 static WatchpointOptions *CopyOptionsNoCallback(WatchpointOptions &rhs);
45 //------------------------------------------------------------------
46 /// This constructor allows you to specify all the watchpoint options.
48 /// @param[in] callback
49 /// This is the plugin for some code that gets run, returns \b true if we
53 /// Client data that will get passed to the callback.
55 /// @param[in] thread_id
56 /// Only stop if \a thread_id hits the watchpoint.
57 //------------------------------------------------------------------
58 WatchpointOptions(WatchpointHitCallback callback, void *baton,
59 lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
61 virtual ~WatchpointOptions();
63 //------------------------------------------------------------------
65 //------------------------------------------------------------------
66 const WatchpointOptions &operator=(const WatchpointOptions &rhs);
68 //------------------------------------------------------------------
71 // Watchpoint callbacks come in two forms, synchronous and asynchronous.
72 // Synchronous callbacks will get
73 // run before any of the thread plans are consulted, and if they return false
74 // the target will continue
75 // "under the radar" of the thread plans. There are a couple of restrictions
76 // to synchronous callbacks:
77 // 1) They should NOT resume the target themselves. Just return false if you
78 // want the target to restart.
79 // 2) Watchpoints with synchronous callbacks can't have conditions (or rather,
80 // they can have them, but they
81 // won't do anything. Ditto with ignore counts, etc... You are supposed
82 // to control that all through the
84 // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
85 // thread plan. The logic there is:
86 // a) If the watchpoint is thread specific and not for this thread, continue
87 // w/o running the callback.
88 // b) If the ignore count says we shouldn't stop, then ditto.
89 // c) If the condition says we shouldn't stop, then ditto.
90 // d) Otherwise, the callback will get run, and if it returns true we will
91 // stop, and if false we won't.
92 // The asynchronous callback can run the target itself, but at present that
93 // should be the last action the
94 // callback does. We will relax this condition at some point, but it will
95 // take a bit of plumbing to get
98 //------------------------------------------------------------------
100 //------------------------------------------------------------------
101 /// Adds a callback to the watchpoint option set.
103 /// @param[in] callback
104 /// The function to be called when the watchpoint gets hit.
106 /// @param[in] baton_sp
107 /// A baton which will get passed back to the callback when it is invoked.
109 /// @param[in] synchronous
110 /// Whether this is a synchronous or asynchronous callback. See discussion
112 //------------------------------------------------------------------
113 void SetCallback(WatchpointHitCallback callback,
114 const lldb::BatonSP &baton_sp, bool synchronous = false);
116 //------------------------------------------------------------------
117 /// Remove the callback from this option set.
118 //------------------------------------------------------------------
119 void ClearCallback();
121 // The rest of these functions are meant to be used only within the watchpoint
122 // handling mechanism.
124 //------------------------------------------------------------------
125 /// Use this function to invoke the callback for a specific stop.
127 /// @param[in] context
128 /// The context in which the callback is to be invoked. This includes the
130 /// execution context of the stop (since you might hit the same watchpoint
131 /// on multiple threads) and
132 /// whether we are currently executing synchronous or asynchronous
135 /// @param[in] watch_id
136 /// The watchpoint ID that owns this option set.
139 /// The callback return value.
140 //------------------------------------------------------------------
141 bool InvokeCallback(StoppointCallbackContext *context,
142 lldb::user_id_t watch_id);
144 //------------------------------------------------------------------
145 /// Used in InvokeCallback to tell whether it is the right time to run this
146 /// kind of callback.
149 /// The synchronicity of our callback.
150 //------------------------------------------------------------------
151 bool IsCallbackSynchronous() { return m_callback_is_synchronous; }
153 //------------------------------------------------------------------
154 /// Fetch the baton from the callback.
158 //------------------------------------------------------------------
161 //------------------------------------------------------------------
162 /// Fetch a const version of the baton from the callback.
166 //------------------------------------------------------------------
167 const Baton *GetBaton() const;
169 //------------------------------------------------------------------
170 /// Return the current thread spec for this option. This will return nullptr
172 /// specifications have been set for this Option yet.
174 /// The thread specification pointer for this option, or nullptr if none
177 //------------------------------------------------------------------
178 const ThreadSpec *GetThreadSpecNoCreate() const;
180 //------------------------------------------------------------------
181 /// Returns a pointer to the ThreadSpec for this option, creating it.
182 /// if it hasn't been created already. This API is used for setting the
183 /// ThreadSpec items for this option.
184 //------------------------------------------------------------------
185 ThreadSpec *GetThreadSpec();
187 void SetThreadID(lldb::tid_t thread_id);
189 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
191 //------------------------------------------------------------------
192 /// Get description for callback only.
193 //------------------------------------------------------------------
194 void GetCallbackDescription(Stream *s, lldb::DescriptionLevel level) const;
196 //------------------------------------------------------------------
197 /// Returns true if the watchpoint option has a callback set.
198 //------------------------------------------------------------------
201 //------------------------------------------------------------------
202 /// This is the default empty callback.
204 /// The thread id for which the watchpoint hit will stop,
205 /// LLDB_INVALID_THREAD_ID for all threads.
206 //------------------------------------------------------------------
207 static bool NullCallback(void *baton, StoppointCallbackContext *context,
208 lldb::user_id_t watch_id);
211 CommandData() : user_source(), script_source(), stop_on_error(true) {}
213 ~CommandData() = default;
215 StringList user_source;
216 std::string script_source;
220 class CommandBaton : public TypedBaton<CommandData> {
222 CommandBaton(std::unique_ptr<CommandData> Data)
223 : TypedBaton(std::move(Data)) {}
225 void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
229 //------------------------------------------------------------------
230 // Classes that inherit from WatchpointOptions can see and modify these
231 //------------------------------------------------------------------
234 //------------------------------------------------------------------
235 // For WatchpointOptions only
236 //------------------------------------------------------------------
237 WatchpointHitCallback m_callback; // This is the callback function pointer
238 lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
239 bool m_callback_is_synchronous;
240 std::unique_ptr<ThreadSpec>
241 m_thread_spec_ap; // Thread for which this watchpoint will take
244 } // namespace lldb_private
246 #endif // liblldb_WatchpointOptions_h_