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 LLDB_BREAKPOINT_WATCHPOINTOPTIONS_H
10#define LLDB_BREAKPOINT_WATCHPOINTOPTIONS_H
11
12#include <memory>
13#include <string>
14
15#include "lldb/Utility/Baton.h"
17#include "lldb/lldb-private.h"
18
19namespace lldb_private {
20
21/// \class WatchpointOptions WatchpointOptions.h
22/// "lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a
23/// watchpoint.
24
26public:
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
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.
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 {
169 CommandData() = default;
170
171 ~CommandData() = default;
172
174 std::string script_source;
175 bool stop_on_error = true;
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(llvm::raw_ostream &s, lldb::DescriptionLevel level,
184 unsigned indentation) const override;
185 };
186
187protected:
188 // Classes that inherit from WatchpointOptions can see and modify these
189
190private:
191 // For WatchpointOptions only
192 WatchpointHitCallback m_callback; // This is the callback function pointer
193 lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
195 std::unique_ptr<ThreadSpec>
196 m_thread_spec_up; // Thread for which this watchpoint will take
197};
198
199} // namespace lldb_private
200
201#endif // LLDB_BREAKPOINT_WATCHPOINTOPTIONS_H
A class designed to wrap callback batons so they can cleanup any acquired resources.
Definition: Baton.h:35
General Outline: When we hit a breakpoint we need to package up whatever information is needed to eva...
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
CommandBaton(std::unique_ptr< CommandData > Data)
void GetDescription(llvm::raw_ostream &s, lldb::DescriptionLevel level, unsigned indentation) const override
"lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a watchpoint.
const WatchpointOptions & operator=(const WatchpointOptions &rhs)
static WatchpointOptions * CopyOptionsNoCallback(WatchpointOptions &rhs)
void SetThreadID(lldb::tid_t thread_id)
void ClearCallback()
Remove the callback from this option set.
bool HasCallback()
Returns true if the watchpoint option has a callback set.
std::unique_ptr< ThreadSpec > m_thread_spec_up
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.
bool InvokeCallback(StoppointCallbackContext *context, lldb::user_id_t watch_id)
Use this function to invoke the callback for a specific stop.
void SetCallback(WatchpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous=false)
Adds a callback to the watchpoint option set.
WatchpointHitCallback m_callback
void GetCallbackDescription(Stream *s, lldb::DescriptionLevel level) const
Get description for callback only.
WatchpointOptions()
Default constructor.
const ThreadSpec * GetThreadSpecNoCreate() const
Return the current thread spec for this option.
bool IsCallbackSynchronous()
Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
Baton * GetBaton()
Fetch the baton from the callback.
WatchpointOptions(WatchpointHitCallback callback, void *baton, lldb::tid_t thread_id=LLDB_INVALID_THREAD_ID)
This constructor allows you to specify all the watchpoint options.
ThreadSpec * GetThreadSpec()
Returns a pointer to the ThreadSpec for this option, creating it.
#define LLDB_INVALID_THREAD_ID
Definition: lldb-defines.h:82
A class that represents a running process on the host machine.
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
uint64_t user_id_t
Definition: lldb-types.h:84
uint64_t tid_t
Definition: lldb-types.h:86