debugger_client.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef ZORBA_DEBUGGER_CLIENT_H
17 #define ZORBA_DEBUGGER_CLIENT_H
18 
19 #include <map>
20 #include <list>
21 #include <vector>
22 
23 #include <zorba/api_shared_types.h>
25 #include <zorba/query_location.h>
26 
27 namespace zorba {
28 
29  /**
30  * Representation of the runtime stack frame.
31  */
32  class ZORBA_DLL_PUBLIC StackFrame
33  {
34  public:
35 
36  virtual
38 
39  virtual const std::string&
40  getSignature() const = 0;
41 
42  virtual const QueryLocation&
43  getLocation() const = 0;
44  };
45 
46  //string serialization of the query
47  ZORBA_DLL_PUBLIC
48  std::ostream& operator<< (std::ostream& os, const QueryLocation& aQuery);
49  ZORBA_DLL_PUBLIC
50  std::ostream& operator<< (std::ostream& os, const QueryLocation* aQuery);
51 
52  /**
53  * @brief A DBGP client implementation for commands.
54  *
55  * This is the client implementation for sending commands
56  * according to the specification of DBGP. DBGP is used as
57  * the default communication format in the Zorba debugger.
58  */
59  class ZORBA_DLL_PUBLIC DebuggerClient {
60  public:
61  /**
62  * @brief creates a new instance of a DebuggerClient implementation.
63  *
64  * @param aHandler The event handler, where answered should get delivered to.
65  * @param aPort The port the client should listen to.
66  * @param aHost the host the client should listen to
67  * @return A DebuggerClient implementation.
68  */
69  static DebuggerClient* createDebuggerClient(DebuggerEventHandler* aHandler,
70  unsigned short aPort,
71  const std::string& aHost);
72  public:
73  virtual ~DebuggerClient();
74  public: // Types
75  typedef enum {
81  Watch
82  } BreakpointType;
83  typedef enum {
86  Multiple
87  } HitCondition;
88  typedef enum {
91  Stdin
92  } OutputStream;
93  typedef enum {
96  Redirection
97  } StreamBehaviour;
98  public: // API
99  /**
100  * @brief Waits for a debug engine to attach.
101  *
102  * This method blocks until a debug engine attaches and sends the
103  * init message. After that process, the appropriate method in the
104  * DebugHandler gets called.
105  */
106  virtual void accept() = 0;
107 
108  /**
109  * The status command is a simple way for the IDE to find out from
110  * the debugger engine whether execution may be continued or not. no
111  * body is required on request. If async support has been negotiated
112  * using feature_get/set the status command may be sent while the
113  * debugger engine is in a 'run state'.
114  *
115  * The status attribute values of the response may be:
116  *
117  * <ul>
118  * <li>
119  * starting:
120  * State prior to execution of any code
121  * </li>
122  * <li>
123  * stopping:
124  * State after completion of code execution.
125  * This typically happens at the end of code execution, allowing
126  * the IDE to further interact with the debugger engine (for example,
127  * to collect performance data, or use other extended commands).
128  * </li>
129  * <li>
130  * stopped:
131  * IDE is detached from process, no further interaction is possible.
132  * </li>
133  * <li>
134  * running:
135  * code is currently executing. Note that this state would only be
136  * seen with async support turned on, otherwise the typical state during
137  * IDE/debugger interaction would be 'break'
138  * </li>
139  * <li>
140  * break:
141  * code execution is paused, for whatever reason (see below), and the
142  * IDE/debugger can pass information back and forth.
143  * </li>
144  * </ul>
145  * The reason attribute value may be:
146  *
147  * <ul>
148  * <li>
149  * ok
150  * </li>
151  * <li>
152  * error
153  * </li>
154  * <li>
155  * aborted
156  * </li>
157  * <li>
158  * exception
159  * </li>
160  * </ul>
161  *
162  * @return The id of the request.
163  */
164  virtual std::size_t status() = 0;
165 
166  /**
167  * @brief Get the variables in all the contexts in the topmost stack frame.
168  *
169  * @return The id of the request.
170  */
171  virtual std::size_t variables() = 0;
172 
173  /**
174  * @brief Query the debug engine for supported features.
175  *
176  * @param aFeatureName The name of the feature to query for. values that must be
177  * supported by the debug engine are:
178  * <ul>
179  * <li>
180  * language_supports_threads
181  * </li>
182  * <li>
183  * language_name
184  * </li>
185  * <li>
186  * language_version
187  * </li>
188  * <li>
189  * encoding
190  * </li>
191  * <li>
192  * protocol_version
193  * </li>
194  * <li>
195  * supports_async
196  * </li>
197  * <li>
198  * data_encoding
199  * </li>
200  * <li>
201  * breakpoint_languages
202  * </li>
203  * <li>
204  * breakpoint_types
205  * </li>
206  * </ul>
207  * @return The id of this request
208  */
209  virtual std::size_t feature_get(const std::string& aFeatureName) = 0;
210 
211  /**
212  * @brief Set a specific feature of the engine.
213  *
214  * @param aFeatureName The name of the feature to query for. Values
215  * that must be supported by the debug engine are:
216  * <ul>
217  * <li>
218  * encoding
219  * </li>
220  * <li>
221  * multiple_sessions
222  * </li>
223  * <li>
224  * max_children
225  * </li>
226  * <li>
227  * max_children
228  * </li>
229  * <li>
230  * max_depth
231  * </li>
232  * </ul>
233  * @param aValue The value of the feature
234  * @return The id of this request
235  */
236  virtual std::size_t feature_set(const std::string& aFeatureName,
237  const std::string& aValue) = 0;
238 
239  /**
240  * @brief Send the run command to the debug engine.
241  *
242  * Sending this command to the debug engine makes the debug engine
243  * to start if possible. Otherwise it must report an error.
244  *
245  * @return The id of this request
246  */
247  virtual std::size_t run() = 0;
248 
249  /**
250  * @brief Send the step into command to the debug engine.
251  *
252  * @return The id of this request
253  */
254  virtual std::size_t step_into() = 0;
255 
256  /**
257  * @brief Send the step out command to the debug engine.
258  *
259  * @return The id of this request
260  */
261  virtual std::size_t step_out() = 0;
262 
263  /**
264  * @brief Send the step over command to the debug engine.
265  *
266  * @return The id of this request
267  */
268  virtual std::size_t step_over() = 0;
269 
270  /**
271  * @brief Send the stop command to the debug engine.
272  *
273  * This command tells the debug engine, that it should
274  * break the execution at the next point possible.
275  *
276  * @param withQuit This is a Zorba extension of the DBGP protocol that
277  * controls if the client should terminate execution and quit (true)
278  * or only terminate execution but not quit (false). This is used
279  * by command line clients that implement multiple query runs.
280  * @return The id of this request
281  */
282  virtual std::size_t stop(bool withQuit) = 0;
283 
284  /**
285  * @brief Send the detach command to the debug engine.
286  *
287  * @return The id of this request
288  */
289  virtual std::size_t detach() = 0;
290 
291  /**
292  * @brief Send a command to the debug engine to set a new breakpoint.
293  *
294  * @param aType The type of the breakpoint (line, call, return etc.).
295  * @param aEnabled Should the breakpoint be enabled?
296  * @param aLinenumber The line number where to set the breakpoint.
297  * @param aFilename The file where a breakpoint should be set.
298  * @param aFunctionName The name of the function where to break (only
299  * to be used if aType == Call || aType == Return)
300  * @param aExceptionName The name of the exception to break (only to be used
301  * if aType == Exception)
302  * @param hit_value A numeric value used together with the hit_condition
303  * to determine if the breakpoint should pause execution
304  * or be skipped.
305  * @param aCondition The condition used together with 'hit_value' (default
306  * is '>=')
307  * @param aIsTemporary Flag to define if breakpoint is temporary. A
308  * temporary breakpoint is one that is deleted after
309  * its first use. This is useful for features like "Run
310  * to Cursor". Once the debugger engine uses a temporary
311  * breakpoint, it should automatically remove the
312  * breakpoint from it's list of valid breakpoints.
313  * @param aExpression code expression, in the language of the debugger engine.
314  * The breakpoint should activate when the evaluated code
315  * evaluates to true. (required for conditional breakpoint
316  * types)
317  * @return The id of this request
318  */
319  virtual std::size_t breakpoint_set(BreakpointType aType,
320  bool aEnabled = true,
321  const std::string& aFilename = "",
322  int aLinenumber = -1,
323  const std::string& aFunctionName = "",
324  const std::string& aExceptionName = "",
325  unsigned hit_value = 0,
326  HitCondition aCondition = BiggerEqual,
327  bool aIsTemporary = false,
328  const std::string& aExpression = "") = 0;
329 
330  /**
331  * @brief Get information about a breakpoint.
332  *
333  * @param aBreakpointId The id of the breakpoint.
334  * @return The id of this request
335  */
336  virtual std::size_t breakpoint_get(std::size_t aBreakpointId) = 0;
337 
338  /**
339  * @brief Send a command to the debug engine to update a breakpoint.
340  *
341  * @param aBreakpointId The id of the breakpoint.
342  * @param aEnabled Should the breakpoint be enabled?
343  * @param aLinenumber The line number where to set the breakpoint.
344  * @param hit_value A numeric value used together with the hit_condition
345  * to determine if the breakpoint should pause execution
346  * or be skipped.
347  * @param aCondition The condition used together with 'hit_value' (default
348  * is '>=')
349  * @return The id of this request
350  */
351  virtual std::size_t breakpoint_update(std::size_t aBreakpointId,
352  bool aEnabled = true,
353  int aLinenumber = -1,
354  unsigned hit_value = 0,
355  HitCondition aCondition = BiggerEqual) = 0;
356 
357  /**
358  * @brief Remove a breakpoint.
359  *
360  * @param aBreakpointId The id of the breakpoint.
361  * @return The id of this request
362  */
363  virtual std::size_t breakpoint_remove(std::size_t aBreakpointId) = 0;
364 
365  /**
366  * @brief Query all breakpoints.
367  *
368  * @return The id of this request
369  */
370  virtual std::size_t breakpoint_list() = 0;
371 
372  /**
373  * @brief Get the depth of the stack.
374  *
375  * @return The id of this request
376  */
377  virtual std::size_t stack_depth() = 0;
378 
379  /**
380  * @brief Get information about the stack at a given depth.
381  *
382  * @param depth The depth on which to quey (optional)
383  * @return The id of this request
384  */
385  virtual std::size_t stack_get(int depth = -1) = 0;
386 
387  /**
388  * @brief Get the context names at a given stack depth.
389  *
390  * The context names are the names in which variables are
391  * (like global, local etc.).
392  *
393  * @param depth The depth on which to quey (optional)
394  * @return The id of this request
395  */
396  virtual std::size_t context_names(int depth = -1) = 0;
397 
398  /**
399  * @brief Get the context at a given stack depth.
400  *
401  * Returns an array of properties in a given context at a given
402  * stack depth. If the stack depth is omitted, the current stack
403  * depth is used. If the context name is omitted, the context
404  * with an id zero is used (generally the 'locals' context).
405  *
406  * @param depth The depth on which to quey (optional)
407  * @param contextId The contextId (optional)
408  * @return The id of this request
409  */
410  virtual std::size_t context_get(int depth = -1, int contextId = -1) = 0;
411 
412  /**
413  * @brief Get a mapping of types.
414  *
415  * The IDE calls this command to get information on how to map
416  * language specific type names (as received in the property
417  * element returned by the context_get, and property_* commands).
418  * The debugger engine returns all data types that it supports. There
419  * may be multiple map elements with the same type attribute value,
420  * but the name value must be unique. This allows a language to map
421  * multiple language specific types into one of the common data types
422  * (eg. float and double can both be mapped to float).
423  *
424  * @return The id of this request
425  */
426  virtual std::size_t typemap_get() = 0;
427 
428  /**
429  * @brief Get a property
430  *
431  * @param aPropertyLongName roperty long name (required)
432  * @param aStackDepth stack depth (optional)
433  * @param aContextId The context id for which to query.
434  * @param aMaxDataSize The maximal size of the data sent back
435  * from the debug engine.
436  * @param aDatapage
437  * @param aPropertyKey
438  * @return The id of this request
439  */
440  virtual std::size_t property_get(const std::string& aPropertyLongName,
441  int aStackDepth = -1,
442  int aContextId = -1,
443  std::size_t aMaxDataSize = 0,
444  int aDatapage = -1,
445  const std::string& aPropertyKey = "") = 0;
446 
447  /**
448  * @brief Set a property
449  *
450  * @param aPropertyLongName roperty long name (required)
451  * @param aStackDepth stack depth (optional)
452  * @param aContextId The context id for which to query.
453  * @param aMaxDataSize The maximal size of the data sent back
454  * from the debug engine.
455  * @param aPropertyAddress property address as retrieved in a
456  * property element (optional).
457  * @return The id of this request
458  */
459  virtual std::size_t property_set(const std::string& aPropertyLongName,
460  int aStackDepth = -1,
461  int aContextId = -1,
462  std::size_t aMaxDataSize = 0,
463  const std::string& aPropertyAddress = "") = 0;
464 
465  /**
466  * @brief Get the value of a property
467  *
468  * @param aPropertyLongName roperty long name (required)
469  * @param aStackDepth stack depth (optional)
470  * @param aContextId The context id for which to query.
471  * @param aMaxDataSize The maximal size of the data sent back
472  * from the debug engine.
473  * @param aDatapage
474  * @param aPropertyKey property key as retrieved in a property
475  * element (optional)
476  * @param aPropertyAddress property address as retrieved in a
477  * property element (optional).
478  * @return The id of this request
479  */
480  virtual std::size_t property_value(const std::string& aPropertyLongName,
481  int aStackDepth = -1,
482  int aContextId = -1,
483  std::size_t aMaxDataSize = 0,
484  int aDatapage = -1,
485  const std::string& aPropertyKey = "",
486  const std::string& aPropertyAddress = "") = 0;
487 
488  /**
489  * @brief List the source code at a given position.
490  *
491  * @param aFile The URI of the file the debug engine should deliver.
492  * @param aBeginLine The starting point on which line the debug engine
493  * should start to read.
494  * @param aEndLine The line number where the debug engine should stop
495  * reading from the file.
496  * @return The id of this request.
497  */
498  virtual std::size_t source(const std::string& aFile, unsigned aBeginLine = 0, unsigned aEndLine = 0) = 0;
499 
500  /**
501  * @brief Setting a stream option.
502  *
503  * This method is used to tell the debug engine how to handle I/O. The debug
504  * engine either reads and writes from/to stdin/stdout or it can also copy it
505  * to the client or it can read/write everything from the client.
506  *
507  * @param aStream Specifies for which stream the option should be changed.
508  * @param aBehaviour Specifies which behaviour the debug client should have
509  * for reading/writing.
510  * @return The id of this request
511  */
512  virtual std::size_t stream_option(OutputStream aStream, StreamBehaviour aBehaviour) = 0;
513 
514  /**
515  * @brief Tell the debug engine to stop execution as fast as possible.
516  *
517  * @return The id of this request
518  */
519  virtual std::size_t do_break() = 0;
520 
521  /**
522  * @brief Evaluates an expression.
523  *
524  * @param aExpr The expression to evaluate.
525  * @return The id of this request
526  */
527  virtual std::size_t eval(const std::string& aExpr) = 0;
528 
529  /**
530  * @brief Tells the client to quit. This method blocks until the client quit
531  * successfully.
532  */
533  virtual void quit() = 0;
534  };
535 
536 }//end of namespace
537 
538 #endif