1 //===-- BreakpointOptions.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_BreakpointOptions_h_
11 #define liblldb_BreakpointOptions_h_
18 // Other libraries and framework includes
20 #include "lldb/lldb-private.h"
21 #include "lldb/Core/Baton.h"
22 #include "lldb/Core/StringList.h"
24 namespace lldb_private {
26 //----------------------------------------------------------------------
27 /// @class BreakpointOptions BreakpointOptions.h "lldb/Breakpoint/BreakpointOptions.h"
28 /// @brief Class that manages the options on a breakpoint or breakpoint location.
29 //----------------------------------------------------------------------
31 class BreakpointOptions
34 //------------------------------------------------------------------
35 // Constructors and Destructors
36 //------------------------------------------------------------------
37 //------------------------------------------------------------------
38 /// Default constructor. The breakpoint is enabled, and has no condition,
39 /// callback, ignore count, etc...
40 //------------------------------------------------------------------
42 BreakpointOptions(const BreakpointOptions& rhs);
44 static BreakpointOptions *
45 CopyOptionsNoCallback (BreakpointOptions &rhs);
46 //------------------------------------------------------------------
47 /// This constructor allows you to specify all the breakpoint options.
49 /// @param[in] condition
50 /// The expression which if it evaluates to \b true if we are to stop
52 /// @param[in] callback
53 /// This is the plugin for some code that gets run, returns \b true if we are to stop.
56 /// Client data that will get passed to the callback.
58 /// @param[in] enabled
59 /// Is this breakpoint enabled.
62 /// How many breakpoint hits we should ignore before stopping.
64 /// @param[in] thread_id
65 /// Only stop if \a thread_id hits the breakpoint.
66 //------------------------------------------------------------------
67 BreakpointOptions(void *condition,
68 BreakpointHitCallback callback,
72 lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID,
73 bool one_shot = false);
75 virtual ~BreakpointOptions();
77 //------------------------------------------------------------------
79 //------------------------------------------------------------------
80 const BreakpointOptions&
81 operator=(const BreakpointOptions& rhs);
83 //------------------------------------------------------------------
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
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
105 //------------------------------------------------------------------
107 //------------------------------------------------------------------
108 /// Adds a callback to the breakpoint option set.
110 /// @param[in] callback
111 /// The function to be called when the breakpoint gets hit.
113 /// @param[in] baton_sp
114 /// A baton which will get passed back to the callback when it is invoked.
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);
121 //------------------------------------------------------------------
122 /// Remove the callback from this option set.
123 //------------------------------------------------------------------
124 void ClearCallback ();
126 // The rest of these functions are meant to be used only within the breakpoint handling mechanism.
128 //------------------------------------------------------------------
129 /// Use this function to invoke the callback for a specific stop.
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.
136 /// @param[in] break_id
137 /// The breakpoint ID that owns this option set.
139 /// @param[in] break_loc_id
140 /// The breakpoint location ID that owns this option set.
143 /// The callback return value.
144 //------------------------------------------------------------------
145 bool InvokeCallback (StoppointCallbackContext *context, lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
147 //------------------------------------------------------------------
148 /// Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
151 /// The synchronicity of our callback.
152 //------------------------------------------------------------------
153 bool IsCallbackSynchronous () const
155 return m_callback_is_synchronous;
158 //------------------------------------------------------------------
159 /// Fetch the baton from the callback.
163 //------------------------------------------------------------------
166 //------------------------------------------------------------------
167 /// Fetch a const version of the baton from the callback.
171 //------------------------------------------------------------------
172 const Baton *GetBaton () const;
174 //------------------------------------------------------------------
176 //------------------------------------------------------------------
177 //------------------------------------------------------------------
178 /// Set the breakpoint option's condition.
180 /// @param[in] condition
181 /// The condition expression to evaluate when the breakpoint is hit.
182 //------------------------------------------------------------------
183 void SetCondition (const char *condition);
185 //------------------------------------------------------------------
186 /// Return a pointer to the text of the condition expression.
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;
194 //------------------------------------------------------------------
195 // Enabled/Ignore Count
196 //------------------------------------------------------------------
198 //------------------------------------------------------------------
199 /// Check the Enable/Disable state.
201 /// \b true if the breakpoint is enabled, \b false if disabled.
202 //------------------------------------------------------------------
209 //------------------------------------------------------------------
210 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
211 //------------------------------------------------------------------
213 SetEnabled (bool enabled)
218 //------------------------------------------------------------------
219 /// Check the One-shot state.
221 /// \b true if the breakpoint is one-shot, \b false otherwise.
222 //------------------------------------------------------------------
229 //------------------------------------------------------------------
230 /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
231 //------------------------------------------------------------------
233 SetOneShot (bool one_shot)
235 m_one_shot = one_shot;
238 //------------------------------------------------------------------
239 /// Set the breakpoint to ignore the next \a count breakpoint hits.
241 /// The number of breakpoint hits to ignore.
242 //------------------------------------------------------------------
245 SetIgnoreCount (uint32_t n)
250 //------------------------------------------------------------------
251 /// Return the current Ignore Count.
253 /// The number of breakpoint hits to be ignored.
254 //------------------------------------------------------------------
256 GetIgnoreCount () const
258 return m_ignore_count;
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.
265 /// The thread specification pointer for this option, or nullptr if none has
267 //------------------------------------------------------------------
269 GetThreadSpecNoCreate () const;
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 //------------------------------------------------------------------
280 SetThreadID(lldb::tid_t thread_id);
283 GetDescription (Stream *s, lldb::DescriptionLevel level) const;
285 //------------------------------------------------------------------
286 /// Returns true if the breakpoint option has a callback set.
287 //------------------------------------------------------------------
291 //------------------------------------------------------------------
292 /// This is the default empty callback.
294 /// The thread id for which the breakpoint hit will stop,
295 /// LLDB_INVALID_THREAD_ID for all threads.
296 //------------------------------------------------------------------
298 NullCallback (void *baton,
299 StoppointCallbackContext *context,
300 lldb::user_id_t break_id,
301 lldb::user_id_t break_loc_id);
312 ~CommandData() = default;
314 StringList user_source;
315 std::string script_source;
319 class CommandBaton : public Baton
322 CommandBaton (CommandData *data) :
327 ~CommandBaton() override
329 delete ((CommandData *)m_data);
334 GetDescription (Stream *s, lldb::DescriptionLevel level) const override;
338 //------------------------------------------------------------------
339 // Classes that inherit from BreakpointOptions can see and modify these
340 //------------------------------------------------------------------
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;
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.
357 } // namespace lldb_private
359 #endif // liblldb_BreakpointOptions_h_