debugger_client.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus