00001 /* 00002 * Copyright 2006-2008 The FLWOR Foundation. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef ZORBA_DEBUGGER_CLIENT_H 00017 #define ZORBA_DEBUGGER_CLIENT_H 00018 00019 #include <map> 00020 #include <list> 00021 #include <vector> 00022 00023 #include <zorba/api_shared_types.h> 00024 #include <zorba/debugger_event_handler.h> 00025 #include <zorba/query_location.h> 00026 00027 namespace zorba { 00028 00029 /** 00030 * Representation of the runtime stack frame. 00031 */ 00032 class ZORBA_DLL_PUBLIC StackFrame 00033 { 00034 public: 00035 00036 virtual 00037 ~StackFrame() {} 00038 00039 virtual const std::string& 00040 getSignature() const = 0; 00041 00042 virtual const QueryLocation& 00043 getLocation() const = 0; 00044 }; 00045 00046 //string serialization of the query 00047 ZORBA_DLL_PUBLIC 00048 std::ostream& operator<< (std::ostream& os, const QueryLocation& aQuery); 00049 ZORBA_DLL_PUBLIC 00050 std::ostream& operator<< (std::ostream& os, const QueryLocation* aQuery); 00051 00052 /** 00053 * @brief A DBGP client implementation for commands. 00054 * 00055 * This is the client implementation for sending commands 00056 * according to the specification of DBGP. DBGP is used as 00057 * the default communication format in the Zorba debugger. 00058 */ 00059 class ZORBA_DLL_PUBLIC DebuggerClient { 00060 public: 00061 /** 00062 * @brief creates a new instance of a DebuggerClient implementation. 00063 * 00064 * @param aHandler The event handler, where answered should get delivered to. 00065 * @param aPort The port the client should listen to. 00066 * @param aHost the host the client should listen to 00067 * @return A DebuggerClient implementation. 00068 */ 00069 static DebuggerClient* createDebuggerClient(DebuggerEventHandler* aHandler, 00070 unsigned short aPort, 00071 const std::string& aHost); 00072 public: 00073 virtual ~DebuggerClient(); 00074 public: // Types 00075 typedef enum { 00076 Line, 00077 Call, 00078 Return, 00079 Exception, 00080 Conditional, 00081 Watch 00082 } BreakpointType; 00083 typedef enum { 00084 BiggerEqual, 00085 Equal, 00086 Multiple 00087 } HitCondition; 00088 typedef enum { 00089 Stdout, 00090 Stderr, 00091 Stdin 00092 } OutputStream; 00093 typedef enum { 00094 Disable, 00095 CopyData, 00096 Redirection 00097 } StreamBehaviour; 00098 public: // API 00099 /** 00100 * @brief Waits for a debug engine to attach. 00101 * 00102 * This method blocks until a debug engine attaches and sends the 00103 * init message. After that process, the appropriate method in the 00104 * DebugHandler gets called. 00105 */ 00106 virtual void accept() = 0; 00107 00108 /** 00109 * The status command is a simple way for the IDE to find out from 00110 * the debugger engine whether execution may be continued or not. no 00111 * body is required on request. If async support has been negotiated 00112 * using feature_get/set the status command may be sent while the 00113 * debugger engine is in a 'run state'. 00114 * 00115 * The status attribute values of the response may be: 00116 * 00117 * <ul> 00118 * <li> 00119 * starting: 00120 * State prior to execution of any code 00121 * </li> 00122 * <li> 00123 * stopping: 00124 * State after completion of code execution. 00125 * This typically happens at the end of code execution, allowing 00126 * the IDE to further interact with the debugger engine (for example, 00127 * to collect performance data, or use other extended commands). 00128 * </li> 00129 * <li> 00130 * stopped: 00131 * IDE is detached from process, no further interaction is possible. 00132 * </li> 00133 * <li> 00134 * running: 00135 * code is currently executing. Note that this state would only be 00136 * seen with async support turned on, otherwise the typical state during 00137 * IDE/debugger interaction would be 'break' 00138 * </li> 00139 * <li> 00140 * break: 00141 * code execution is paused, for whatever reason (see below), and the 00142 * IDE/debugger can pass information back and forth. 00143 * </li> 00144 * </ul> 00145 * The reason attribute value may be: 00146 * 00147 * <ul> 00148 * <li> 00149 * ok 00150 * </li> 00151 * <li> 00152 * error 00153 * </li> 00154 * <li> 00155 * aborted 00156 * </li> 00157 * <li> 00158 * exception 00159 * </li> 00160 * </ul> 00161 * 00162 * @return The id of the request. 00163 */ 00164 virtual std::size_t status() = 0; 00165 00166 /** 00167 * @brief Query the debug engine for supported features. 00168 * 00169 * @param aFeatureName The name of the feature to query for. values that must be 00170 * supported by the debug engine are: 00171 * <ul> 00172 * <li> 00173 * language_supports_threads 00174 * </li> 00175 * <li> 00176 * language_name 00177 * </li> 00178 * <li> 00179 * language_version 00180 * </li> 00181 * <li> 00182 * encoding 00183 * </li> 00184 * <li> 00185 * protocol_version 00186 * </li> 00187 * <li> 00188 * supports_async 00189 * </li> 00190 * <li> 00191 * data_encoding 00192 * </li> 00193 * <li> 00194 * breakpoint_languages 00195 * </li> 00196 * <li> 00197 * breakpoint_types 00198 * </li> 00199 * </ul> 00200 * @return The id of this request 00201 */ 00202 virtual std::size_t feature_get(const std::string& aFeatureName) = 0; 00203 00204 /** 00205 * @brief Set a specific feature of the engine. 00206 * 00207 * @param aFeatureName The name of the feature to query for. Values 00208 * that must be supported by the debug engine are: 00209 * <ul> 00210 * <li> 00211 * encoding 00212 * </li> 00213 * <li> 00214 * multiple_sessions 00215 * </li> 00216 * <li> 00217 * max_children 00218 * </li> 00219 * <li> 00220 * max_children 00221 * </li> 00222 * <li> 00223 * max_depth 00224 * </li> 00225 * </ul> 00226 * @param aValue The value of the feature 00227 * @return The id of this request 00228 */ 00229 virtual std::size_t feature_set(const std::string& aFeatureName, 00230 const std::string& aValue) = 0; 00231 00232 /** 00233 * @brief Send the run command to the debug engine. 00234 * 00235 * Sending this command to the debug engine makes the debug engine 00236 * to start if possible. Otherwise it must report an error. 00237 * 00238 * @return The id of this request 00239 */ 00240 virtual std::size_t run() = 0; 00241 00242 /** 00243 * @brief Send the step into command to the debug engine. 00244 * 00245 * @return The id of this request 00246 */ 00247 virtual std::size_t step_into() = 0; 00248 00249 /** 00250 * @brief Send the step out command to the debug engine. 00251 * 00252 * @return The id of this request 00253 */ 00254 virtual std::size_t step_out() = 0; 00255 00256 /** 00257 * @brief Send the step over command to the debug engine. 00258 * 00259 * @return The id of this request 00260 */ 00261 virtual std::size_t step_over() = 0; 00262 00263 /** 00264 * @brief Send the stop command to the debug engine. 00265 * 00266 * This command tells the debug engine, that it should 00267 * break the execution at the next point possible. 00268 * 00269 * @return The id of this request 00270 */ 00271 virtual std::size_t stop() = 0; 00272 00273 /** 00274 * @brief Send the detach command to the debug engine. 00275 * 00276 * @return The id of this request 00277 */ 00278 virtual std::size_t detach() = 0; 00279 00280 /** 00281 * @brief Send a command to the debug engine to set a new breakpoint. 00282 * 00283 * @param aType The type of the breakpoint (line, call, return etc.). 00284 * @param aEnabled Should the breakpoint be enabled? 00285 * @param aLinenumber The line number where to set the breakpoint. 00286 * @param aFilename The file where a breakpoint should be set. 00287 * @param aFunctionName The name of the function where to break (only 00288 * to be used if aType == Call || aType == Return) 00289 * @param aExceptionName The name of the exception to break (only to be used 00290 * if aType == Exception) 00291 * @param hit_value A numeric value used together with the hit_condition 00292 * to determine if the breakpoint should pause execution 00293 * or be skipped. 00294 * @param aCondition The condition used together with 'hit_value' (default 00295 * is '>=') 00296 * @param aIsTemporary Flag to define if breakpoint is temporary. A 00297 * temporary breakpoint is one that is deleted after 00298 * its first use. This is useful for features like "Run 00299 * to Cursor". Once the debugger engine uses a temporary 00300 * breakpoint, it should automatically remove the 00301 * breakpoint from it's list of valid breakpoints. 00302 * @param aExpression code expression, in the language of the debugger engine. 00303 * The breakpoint should activate when the evaluated code 00304 * evaluates to true. (required for conditional breakpoint 00305 * types) 00306 * @return The id of this request 00307 */ 00308 virtual std::size_t breakpoint_set(BreakpointType aType, 00309 bool aEnabled = true, 00310 const std::string& aFilename = "", 00311 int aLinenumber = -1, 00312 const std::string& aFunctionName = "", 00313 const std::string& aExceptionName = "", 00314 unsigned hit_value = 0, 00315 HitCondition aCondition = BiggerEqual, 00316 bool aIsTemporary = false, 00317 const std::string& aExpression = "") = 0; 00318 00319 /** 00320 * @brief Get information about a breakpoint. 00321 * 00322 * @param aBreakpointId The id of the breakpoint. 00323 * @return The id of this request 00324 */ 00325 virtual std::size_t breakpoint_get(std::size_t aBreakpointId) = 0; 00326 00327 /** 00328 * @brief Send a command to the debug engine to update a breakpoint. 00329 * 00330 * @param aBreakpointId The id of the breakpoint. 00331 * @param aEnabled Should the breakpoint be enabled? 00332 * @param aLinenumber The line number where to set the breakpoint. 00333 * @param hit_value A numeric value used together with the hit_condition 00334 * to determine if the breakpoint should pause execution 00335 * or be skipped. 00336 * @param aCondition The condition used together with 'hit_value' (default 00337 * is '>=') 00338 * @return The id of this request 00339 */ 00340 virtual std::size_t breakpoint_update(std::size_t aBreakpointId, 00341 bool aEnabled = true, 00342 int aLinenumber = -1, 00343 unsigned hit_value = 0, 00344 HitCondition aCondition = BiggerEqual) = 0; 00345 00346 /** 00347 * @brief Remove a breakpoint. 00348 * 00349 * @param aBreakpointId The id of the breakpoint. 00350 * @return The id of this request 00351 */ 00352 virtual std::size_t breakpoint_remove(std::size_t aBreakpointId) = 0; 00353 00354 /** 00355 * @brief Query all breakpoints. 00356 * 00357 * @return The id of this request 00358 */ 00359 virtual std::size_t breakpoint_list() = 0; 00360 00361 /** 00362 * @brief Get the depth of the stack. 00363 * 00364 * @return The id of this request 00365 */ 00366 virtual std::size_t stack_depth() = 0; 00367 00368 /** 00369 * @brief Get information about the stack at a given depth. 00370 * 00371 * @param depth The depth on which to quey (optional) 00372 * @return The id of this request 00373 */ 00374 virtual std::size_t stack_get(int depth = -1) = 0; 00375 00376 /** 00377 * @brief Get the context names at a given stack depth. 00378 * 00379 * The context names are the names in which variables are 00380 * (like global, local etc.). 00381 * 00382 * @param depth The depth on which to quey (optional) 00383 * @return The id of this request 00384 */ 00385 virtual std::size_t context_names(int depth = -1) = 0; 00386 00387 /** 00388 * @brief Get the context at a given stack depth. 00389 * 00390 * Returns an array of properties in a given context at a given 00391 * stack depth. If the stack depth is omitted, the current stack 00392 * depth is used. If the context name is omitted, the context 00393 * with an id zero is used (generally the 'locals' context). 00394 * 00395 * @param depth The depth on which to quey (optional) 00396 * @param contextId The contextId (optional) 00397 * @return The id of this request 00398 */ 00399 virtual std::size_t context_get(int depth = -1, int contextId = -1) = 0; 00400 00401 /** 00402 * @brief Get a mapping of types. 00403 * 00404 * The IDE calls this command to get information on how to map 00405 * language specific type names (as received in the property 00406 * element returned by the context_get, and property_* commands). 00407 * The debugger engine returns all data types that it supports. There 00408 * may be multiple map elements with the same type attribute value, 00409 * but the name value must be unique. This allows a language to map 00410 * multiple language specific types into one of the common data types 00411 * (eg. float and double can both be mapped to float). 00412 * 00413 * @return The id of this request 00414 */ 00415 virtual std::size_t typemap_get() = 0; 00416 00417 /** 00418 * @brief Get a property 00419 * 00420 * @param aPropertyLongName roperty long name (required) 00421 * @param aStackDepth stack depth (optional) 00422 * @param aContextId The context id for which to query. 00423 * @param aMaxDataSize The maximal size of the data sent back 00424 * from the debug engine. 00425 * @param aDatapage 00426 * @param aPropertyKey 00427 * @return The id of this request 00428 */ 00429 virtual std::size_t property_get(const std::string& aPropertyLongName, 00430 int aStackDepth = -1, 00431 int aContextId = -1, 00432 std::size_t aMaxDataSize = 0, 00433 int aDatapage = -1, 00434 const std::string& aPropertyKey = "") = 0; 00435 00436 /** 00437 * @brief Set a property 00438 * 00439 * @param aPropertyLongName roperty long name (required) 00440 * @param aStackDepth stack depth (optional) 00441 * @param aContextId The context id for which to query. 00442 * @param aMaxDataSize The maximal size of the data sent back 00443 * from the debug engine. 00444 * @param aPropertyAddress property address as retrieved in a 00445 * property element (optional). 00446 * @return The id of this request 00447 */ 00448 virtual std::size_t property_set(const std::string& aPropertyLongName, 00449 int aStackDepth = -1, 00450 int aContextId = -1, 00451 std::size_t aMaxDataSize = 0, 00452 const std::string& aPropertyAddress = "") = 0; 00453 00454 /** 00455 * @brief Get the value of a property 00456 * 00457 * @param aPropertyLongName roperty long name (required) 00458 * @param aStackDepth stack depth (optional) 00459 * @param aContextId The context id for which to query. 00460 * @param aMaxDataSize The maximal size of the data sent back 00461 * from the debug engine. 00462 * @param aDatapage 00463 * @param aPropertyKey property key as retrieved in a property 00464 * element (optional) 00465 * @param aPropertyAddress property address as retrieved in a 00466 * property element (optional). 00467 * @return The id of this request 00468 */ 00469 virtual std::size_t property_value(const std::string& aPropertyLongName, 00470 int aStackDepth = -1, 00471 int aContextId = -1, 00472 std::size_t aMaxDataSize = 0, 00473 int aDatapage = -1, 00474 const std::string& aPropertyKey = "", 00475 const std::string& aPropertyAddress = "") = 0; 00476 00477 /** 00478 * @brief List the source code at a given position. 00479 * 00480 * @param aFile The URI of the file the debug engine should deliver. 00481 * @param aBeginLine The starting point on which line the debug engine 00482 * should start to read. 00483 * @param aEndLine The line number where the debug engine should stop 00484 * reading from the file. 00485 * @return The id of this request. 00486 */ 00487 virtual std::size_t source(const std::string& aFile, unsigned aBeginLine = 0, unsigned aEndLine = 0) = 0; 00488 00489 /** 00490 * @brief Setting a stream option. 00491 * 00492 * This method is used to tell the debug engine how to handle I/O. The debug 00493 * engine either reads and writes from/to stdin/stdout or it can also copy it 00494 * to the client or it can read/write everything from the client. 00495 * 00496 * @param aStream Specifies for which stream the option should be changed. 00497 * @param aBehaviour Specifies which behaviour the debug client should have 00498 * for reading/writing. 00499 * @return The id of this request 00500 */ 00501 virtual std::size_t stream_option(OutputStream aStream, StreamBehaviour aBehaviour) = 0; 00502 00503 /** 00504 * @brief Tell the debug engine to stop execution as fast as possible. 00505 * 00506 * @return The id of this request 00507 */ 00508 virtual std::size_t do_break() = 0; 00509 00510 /** 00511 * @brief Evaluates an expression. 00512 * 00513 * @param aExpr The expression to evaluate. 00514 * @return The id of this request 00515 */ 00516 virtual std::size_t eval(const std::string& aExpr) = 0; 00517 00518 /** 00519 * @brief Tells the client to quit. This method blocks until the client quit 00520 * successfully. 00521 */ 00522 virtual void quit() = 0; 00523 }; 00524 }//end of namespace 00525 #endif 00526 /* vim:set et sw=2 ts=2: */