WatchpointOptions.h revision 81a96aa6242f7b559770f5dc62316253cb8cb0d4 
1//===-- WatchpointOptions.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_WatchpointOptions_h_
11#define liblldb_WatchpointOptions_h_
12
13// C Includes
14// C++ Includes
15// Other libraries and framework includes
16// Project includes
17#include "lldb/lldb-private.h"
18#include "lldb/Core/Baton.h"
19#include "lldb/Core/StringList.h"
20
21namespace lldb_private {
22
23//----------------------------------------------------------------------
24/// @class WatchpointOptions WatchpointOptions.h "lldb/Breakpoint/WatchpointOptions.h"
25/// @brief Class that manages the options on a watchpoint.
26//----------------------------------------------------------------------
27
28class WatchpointOptions
29{
30public:
31    //------------------------------------------------------------------
32    // Constructors and Destructors
33    //------------------------------------------------------------------
34    //------------------------------------------------------------------
35    /// Default constructor.  The watchpoint is enabled, and has no condition,
36    /// callback, ignore count, etc...
37    //------------------------------------------------------------------
38    WatchpointOptions();
39    WatchpointOptions(const WatchpointOptions& rhs);
40
41    static WatchpointOptions *
42    CopyOptionsNoCallback (WatchpointOptions &rhs);
43    //------------------------------------------------------------------
44    /// This constructor allows you to specify all the watchpoint options.
45    ///
46    /// @param[in] callback
47    ///    This is the plugin for some code that gets run, returns \b true if we are to stop.
48    ///
49    /// @param[in] baton
50    ///    Client data that will get passed to the callback.
51    ///
52    /// @param[in] thread_id
53    ///    Only stop if \a thread_id hits the watchpoint.
54    //------------------------------------------------------------------
55    WatchpointOptions(WatchpointHitCallback callback,
56                      void *baton,
57                      lldb::tid_t thread_id = LLDB_INVALID_THREAD_ID);
58
59    virtual ~WatchpointOptions();
60
61    //------------------------------------------------------------------
62    // Operators
63    //------------------------------------------------------------------
64    const WatchpointOptions&
65    operator=(const WatchpointOptions& rhs);
66
67    //------------------------------------------------------------------
68    // Callbacks
69    //
70    // Watchpoint callbacks come in two forms, synchronous and asynchronous.  Synchronous callbacks will get
71    // run before any of the thread plans are consulted, and if they return false the target will continue
72    // "under the radar" of the thread plans.  There are a couple of restrictions to synchronous callbacks:
73    // 1) They should NOT resume the target themselves.  Just return false if you want the target to restart.
74    // 2) Watchpoints with synchronous callbacks can't have conditions (or rather, they can have them, but they
75    //    won't do anything.  Ditto with ignore counts, etc...  You are supposed to control that all through the
76    //    callback.
77    // Asynchronous callbacks get run as part of the "ShouldStop" logic in the thread plan.  The logic there is:
78    //   a) If the watchpoint is thread specific and not for this thread, continue w/o running the callback.
79    //   b) If the ignore count says we shouldn't stop, then ditto.
80    //   c) If the condition says we shouldn't stop, then ditto.
81    //   d) Otherwise, the callback will get run, and if it returns true we will stop, and if false we won't.
82    //  The asynchronous callback can run the target itself, but at present that should be the last action the
83    //  callback does.  We will relax this condition at some point, but it will take a bit of plumbing to get
84    //  that to work.
85    //
86    //------------------------------------------------------------------
87
88    //------------------------------------------------------------------
89    /// Adds a callback to the watchpoint option set.
90    ///
91    /// @param[in] callback
92    ///    The function to be called when the watchpoint gets hit.
93    ///
94    /// @param[in] baton_sp
95    ///    A baton which will get passed back to the callback when it is invoked.
96    ///
97    /// @param[in] synchronous
98    ///    Whether this is a synchronous or asynchronous callback.  See discussion above.
99    //------------------------------------------------------------------
100    void SetCallback (WatchpointHitCallback callback, const lldb::BatonSP &baton_sp, bool synchronous = false);
101
102
103    //------------------------------------------------------------------
104    /// Remove the callback from this option set.
105    //------------------------------------------------------------------
106    void ClearCallback ();
107
108    // The rest of these functions are meant to be used only within the watchpoint handling mechanism.
109
110    //------------------------------------------------------------------
111    /// Use this function to invoke the callback for a specific stop.
112    ///
113    /// @param[in] context
114    ///    The context in which the callback is to be invoked.  This includes the stop event, the
115    ///    execution context of the stop (since you might hit the same watchpoint on multiple threads) and
116    ///    whether we are currently executing synchronous or asynchronous callbacks.
117    ///
118    /// @param[in] watch_id
119    ///    The watchpoint ID that owns this option set.
120    ///
121    /// @return
122    ///     The callback return value.
123    //------------------------------------------------------------------
124    bool InvokeCallback (StoppointCallbackContext *context, lldb::user_id_t watch_id);
125
126    //------------------------------------------------------------------
127    /// Used in InvokeCallback to tell whether it is the right time to run this kind of callback.
128    ///
129    /// @return
130    ///     The synchronicity of our callback.
131    //------------------------------------------------------------------
132    bool IsCallbackSynchronous () {
133        return m_callback_is_synchronous;
134    }
135
136    //------------------------------------------------------------------
137    /// Fetch the baton from the callback.
138    ///
139    /// @return
140    ///     The baton.
141    //------------------------------------------------------------------
142    Baton *GetBaton ();
143
144    //------------------------------------------------------------------
145    /// Fetch  a const version of the baton from the callback.
146    ///
147    /// @return
148    ///     The baton.
149    //------------------------------------------------------------------
150    const Baton *GetBaton () const;
151
152    //------------------------------------------------------------------
153    /// Return the current thread spec for this option.  This will return NULL if the no thread
154    /// specifications have been set for this Option yet.
155    /// @return
156    ///     The thread specification pointer for this option, or NULL if none has
157    ///     been set yet.
158    //------------------------------------------------------------------
159    const ThreadSpec *
160    GetThreadSpecNoCreate () const;
161
162    //------------------------------------------------------------------
163    /// Returns a pointer to the ThreadSpec for this option, creating it.
164    /// if it hasn't been created already.   This API is used for setting the
165    /// ThreadSpec items for this option.
166    //------------------------------------------------------------------
167    ThreadSpec *
168    GetThreadSpec ();
169
170    void
171    SetThreadID(lldb::tid_t thread_id);
172
173    void
174    GetDescription (Stream *s, lldb::DescriptionLevel level) const;
175
176    //------------------------------------------------------------------
177    /// Get description for callback only.
178    //------------------------------------------------------------------
179    void
180    GetCallbackDescription (Stream *s, lldb::DescriptionLevel level) const;
181
182    //------------------------------------------------------------------
183    /// Returns true if the watchpoint option has a callback set.
184    //------------------------------------------------------------------
185    bool
186    HasCallback();
187
188    //------------------------------------------------------------------
189    /// This is the default empty callback.
190    /// @return
191    ///     The thread id for which the watchpoint hit will stop,
192    ///     LLDB_INVALID_THREAD_ID for all threads.
193    //------------------------------------------------------------------
194    static bool
195    NullCallback (void *baton,
196                  StoppointCallbackContext *context,
197                  lldb::user_id_t watch_id);
198
199
200    struct CommandData
201    {
202        CommandData () :
203            user_source(),
204            script_source(),
205            stop_on_error(true)
206        {
207        }
208
209        ~CommandData ()
210        {
211        }
212
213        StringList user_source;
214        std::string script_source;
215        bool stop_on_error;
216    };
217
218    class CommandBaton : public Baton
219    {
220    public:
221        CommandBaton (CommandData *data) :
222            Baton (data)
223        {
224        }
225
226        virtual
227        ~CommandBaton ()
228        {
229            delete ((CommandData *)m_data);
230            m_data = NULL;
231        }
232
233        virtual void
234        GetDescription (Stream *s, lldb::DescriptionLevel level) const;
235
236    };
237
238protected:
239    //------------------------------------------------------------------
240    // Classes that inherit from WatchpointOptions can see and modify these
241    //------------------------------------------------------------------
242
243private:
244    //------------------------------------------------------------------
245    // For WatchpointOptions only
246    //------------------------------------------------------------------
247    WatchpointHitCallback m_callback; // This is the callback function pointer
248    lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
249    bool m_callback_is_synchronous;
250    STD_UNIQUE_PTR(ThreadSpec) m_thread_spec_ap; // Thread for which this watchpoint will take
251};
252
253} // namespace lldb_private
254
255#endif  // liblldb_WatchpointOptions_h_
256