Public Types | Public Member Functions | Static Public Member Functions | List of all members
zorba::DebuggerClient Class Referenceabstract

A DBGP client implementation for commands. More...

#include <zorba/debugger_client.h>

Public Types

enum  BreakpointType {
  Line, Call, Return, Exception,
  Conditional, Watch
}
 
enum  HitCondition { BiggerEqual, Equal, Multiple }
 
enum  OutputStream { Stdout, Stderr, Stdin }
 
enum  StreamBehaviour { Disable, CopyData, Redirection }
 

Public Member Functions

virtual void accept ()=0
 Waits for a debug engine to attach. More...
 
virtual std::size_t breakpoint_get (std::size_t aBreakpointId)=0
 Get information about a breakpoint. More...
 
virtual std::size_t breakpoint_list ()=0
 Query all breakpoints. More...
 
virtual std::size_t breakpoint_remove (std::size_t aBreakpointId)=0
 Remove a breakpoint. More...
 
virtual std::size_t breakpoint_set (BreakpointType aType, bool aEnabled=true, const std::string &aFilename="", int aLinenumber=-1, const std::string &aFunctionName="", const std::string &aExceptionName="", unsigned hit_value=0, HitCondition aCondition=BiggerEqual, bool aIsTemporary=false, const std::string &aExpression="")=0
 Send a command to the debug engine to set a new breakpoint. More...
 
virtual std::size_t breakpoint_update (std::size_t aBreakpointId, bool aEnabled=true, int aLinenumber=-1, unsigned hit_value=0, HitCondition aCondition=BiggerEqual)=0
 Send a command to the debug engine to update a breakpoint. More...
 
virtual std::size_t context_get (int depth=-1, int contextId=-1)=0
 Get the context at a given stack depth. More...
 
virtual std::size_t context_names (int depth=-1)=0
 Get the context names at a given stack depth. More...
 
virtual std::size_t detach ()=0
 Send the detach command to the debug engine. More...
 
virtual std::size_t do_break ()=0
 Tell the debug engine to stop execution as fast as possible. More...
 
virtual std::size_t eval (const std::string &aExpr)=0
 Evaluates an expression. More...
 
virtual std::size_t feature_get (const std::string &aFeatureName)=0
 Query the debug engine for supported features. More...
 
virtual std::size_t feature_set (const std::string &aFeatureName, const std::string &aValue)=0
 Set a specific feature of the engine. More...
 
virtual std::size_t property_get (const std::string &aPropertyLongName, int aStackDepth=-1, int aContextId=-1, std::size_t aMaxDataSize=0, int aDatapage=-1, const std::string &aPropertyKey="")=0
 Get a property. More...
 
virtual std::size_t property_set (const std::string &aPropertyLongName, int aStackDepth=-1, int aContextId=-1, std::size_t aMaxDataSize=0, const std::string &aPropertyAddress="")=0
 Set a property. More...
 
virtual std::size_t property_value (const std::string &aPropertyLongName, int aStackDepth=-1, int aContextId=-1, std::size_t aMaxDataSize=0, int aDatapage=-1, const std::string &aPropertyKey="", const std::string &aPropertyAddress="")=0
 Get the value of a property. More...
 
virtual void quit ()=0
 Tells the client to quit. More...
 
virtual std::size_t run ()=0
 Send the run command to the debug engine. More...
 
virtual std::size_t source (const std::string &aFile, unsigned aBeginLine=0, unsigned aEndLine=0)=0
 List the source code at a given position. More...
 
virtual std::size_t stack_depth ()=0
 Get the depth of the stack. More...
 
virtual std::size_t stack_get (int depth=-1)=0
 Get information about the stack at a given depth. More...
 
virtual std::size_t status ()=0
 The status command is a simple way for the IDE to find out from the debugger engine whether execution may be continued or not. More...
 
virtual std::size_t step_into ()=0
 Send the step into command to the debug engine. More...
 
virtual std::size_t step_out ()=0
 Send the step out command to the debug engine. More...
 
virtual std::size_t step_over ()=0
 Send the step over command to the debug engine. More...
 
virtual std::size_t stop (bool withQuit)=0
 Send the stop command to the debug engine. More...
 
virtual std::size_t stream_option (OutputStream aStream, StreamBehaviour aBehaviour)=0
 Setting a stream option. More...
 
virtual std::size_t typemap_get ()=0
 Get a mapping of types. More...
 
virtual std::size_t variables ()=0
 Get the variables in all the contexts in the topmost stack frame. More...
 
virtual ~DebuggerClient ()
 

Static Public Member Functions

static DebuggerClientcreateDebuggerClient (DebuggerEventHandler *aHandler, unsigned short aPort, const std::string &aHost)
 creates a new instance of a DebuggerClient implementation. More...
 

Detailed Description

A DBGP client implementation for commands.

This is the client implementation for sending commands according to the specification of DBGP. DBGP is used as the default communication format in the Zorba debugger.

Definition at line 59 of file debugger_client.h.

Member Enumeration Documentation

Enumerator
Line 
Call 
Return 
Exception 
Conditional 
Watch 

Definition at line 75 of file debugger_client.h.

Enumerator
BiggerEqual 
Equal 
Multiple 

Definition at line 83 of file debugger_client.h.

Enumerator
Stdout 
Stderr 
Stdin 

Definition at line 88 of file debugger_client.h.

Enumerator
Disable 
CopyData 
Redirection 

Definition at line 93 of file debugger_client.h.

Constructor & Destructor Documentation

virtual zorba::DebuggerClient::~DebuggerClient ( )
virtual

Member Function Documentation

virtual void zorba::DebuggerClient::accept ( )
pure virtual

Waits for a debug engine to attach.

This method blocks until a debug engine attaches and sends the init message. After that process, the appropriate method in the DebugHandler gets called.

virtual std::size_t zorba::DebuggerClient::breakpoint_get ( std::size_t  aBreakpointId)
pure virtual

Get information about a breakpoint.

Parameters
aBreakpointIdThe id of the breakpoint.
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::breakpoint_list ( )
pure virtual

Query all breakpoints.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::breakpoint_remove ( std::size_t  aBreakpointId)
pure virtual

Remove a breakpoint.

Parameters
aBreakpointIdThe id of the breakpoint.
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::breakpoint_set ( BreakpointType  aType,
bool  aEnabled = true,
const std::string &  aFilename = "",
int  aLinenumber = -1,
const std::string &  aFunctionName = "",
const std::string &  aExceptionName = "",
unsigned  hit_value = 0,
HitCondition  aCondition = BiggerEqual,
bool  aIsTemporary = false,
const std::string &  aExpression = "" 
)
pure virtual

Send a command to the debug engine to set a new breakpoint.

Parameters
aTypeThe type of the breakpoint (line, call, return etc.).
aEnabledShould the breakpoint be enabled?
aLinenumberThe line number where to set the breakpoint.
aFilenameThe file where a breakpoint should be set.
aFunctionNameThe name of the function where to break (only to be used if aType == Call || aType == Return)
aExceptionNameThe name of the exception to break (only to be used if aType == Exception)
hit_valueA numeric value used together with the hit_condition to determine if the breakpoint should pause execution or be skipped.
aConditionThe condition used together with 'hit_value' (default is '>=')
aIsTemporaryFlag to define if breakpoint is temporary. A temporary breakpoint is one that is deleted after its first use. This is useful for features like "Run to Cursor". Once the debugger engine uses a temporary breakpoint, it should automatically remove the breakpoint from it's list of valid breakpoints.
aExpressioncode expression, in the language of the debugger engine. The breakpoint should activate when the evaluated code evaluates to true. (required for conditional breakpoint types)
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::breakpoint_update ( std::size_t  aBreakpointId,
bool  aEnabled = true,
int  aLinenumber = -1,
unsigned  hit_value = 0,
HitCondition  aCondition = BiggerEqual 
)
pure virtual

Send a command to the debug engine to update a breakpoint.

Parameters
aBreakpointIdThe id of the breakpoint.
aEnabledShould the breakpoint be enabled?
aLinenumberThe line number where to set the breakpoint.
hit_valueA numeric value used together with the hit_condition to determine if the breakpoint should pause execution or be skipped.
aConditionThe condition used together with 'hit_value' (default is '>=')
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::context_get ( int  depth = -1,
int  contextId = -1 
)
pure virtual

Get the context at a given stack depth.

Returns an array of properties in a given context at a given stack depth. If the stack depth is omitted, the current stack depth is used. If the context name is omitted, the context with an id zero is used (generally the 'locals' context).

Parameters
depthThe depth on which to quey (optional)
contextIdThe contextId (optional)
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::context_names ( int  depth = -1)
pure virtual

Get the context names at a given stack depth.

The context names are the names in which variables are (like global, local etc.).

Parameters
depthThe depth on which to quey (optional)
Returns
The id of this request
static DebuggerClient* zorba::DebuggerClient::createDebuggerClient ( DebuggerEventHandler aHandler,
unsigned short  aPort,
const std::string &  aHost 
)
static

creates a new instance of a DebuggerClient implementation.

Parameters
aHandlerThe event handler, where answered should get delivered to.
aPortThe port the client should listen to.
aHostthe host the client should listen to
Returns
A DebuggerClient implementation.
virtual std::size_t zorba::DebuggerClient::detach ( )
pure virtual

Send the detach command to the debug engine.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::do_break ( )
pure virtual

Tell the debug engine to stop execution as fast as possible.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::eval ( const std::string &  aExpr)
pure virtual

Evaluates an expression.

Parameters
aExprThe expression to evaluate.
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::feature_get ( const std::string &  aFeatureName)
pure virtual

Query the debug engine for supported features.

Parameters
aFeatureNameThe name of the feature to query for. values that must be supported by the debug engine are:
  • language_supports_threads
  • language_name
  • language_version
  • encoding
  • protocol_version
  • supports_async
  • data_encoding
  • breakpoint_languages
  • breakpoint_types
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::feature_set ( const std::string &  aFeatureName,
const std::string &  aValue 
)
pure virtual

Set a specific feature of the engine.

Parameters
aFeatureNameThe name of the feature to query for. Values that must be supported by the debug engine are:
  • encoding
  • multiple_sessions
  • max_children
  • max_children
  • max_depth
aValueThe value of the feature
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::property_get ( const std::string &  aPropertyLongName,
int  aStackDepth = -1,
int  aContextId = -1,
std::size_t  aMaxDataSize = 0,
int  aDatapage = -1,
const std::string &  aPropertyKey = "" 
)
pure virtual

Get a property.

Parameters
aPropertyLongNameroperty long name (required)
aStackDepthstack depth (optional)
aContextIdThe context id for which to query.
aMaxDataSizeThe maximal size of the data sent back from the debug engine.
aDatapage
aPropertyKey
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::property_set ( const std::string &  aPropertyLongName,
int  aStackDepth = -1,
int  aContextId = -1,
std::size_t  aMaxDataSize = 0,
const std::string &  aPropertyAddress = "" 
)
pure virtual

Set a property.

Parameters
aPropertyLongNameroperty long name (required)
aStackDepthstack depth (optional)
aContextIdThe context id for which to query.
aMaxDataSizeThe maximal size of the data sent back from the debug engine.
aPropertyAddressproperty address as retrieved in a property element (optional).
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::property_value ( const std::string &  aPropertyLongName,
int  aStackDepth = -1,
int  aContextId = -1,
std::size_t  aMaxDataSize = 0,
int  aDatapage = -1,
const std::string &  aPropertyKey = "",
const std::string &  aPropertyAddress = "" 
)
pure virtual

Get the value of a property.

Parameters
aPropertyLongNameroperty long name (required)
aStackDepthstack depth (optional)
aContextIdThe context id for which to query.
aMaxDataSizeThe maximal size of the data sent back from the debug engine.
aDatapage
aPropertyKeyproperty key as retrieved in a property element (optional)
aPropertyAddressproperty address as retrieved in a property element (optional).
Returns
The id of this request
virtual void zorba::DebuggerClient::quit ( )
pure virtual

Tells the client to quit.

This method blocks until the client quit successfully.

virtual std::size_t zorba::DebuggerClient::run ( )
pure virtual

Send the run command to the debug engine.

Sending this command to the debug engine makes the debug engine to start if possible. Otherwise it must report an error.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::source ( const std::string &  aFile,
unsigned  aBeginLine = 0,
unsigned  aEndLine = 0 
)
pure virtual

List the source code at a given position.

Parameters
aFileThe URI of the file the debug engine should deliver.
aBeginLineThe starting point on which line the debug engine should start to read.
aEndLineThe line number where the debug engine should stop reading from the file.
Returns
The id of this request.
virtual std::size_t zorba::DebuggerClient::stack_depth ( )
pure virtual

Get the depth of the stack.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::stack_get ( int  depth = -1)
pure virtual

Get information about the stack at a given depth.

Parameters
depthThe depth on which to quey (optional)
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::status ( )
pure virtual

The status command is a simple way for the IDE to find out from the debugger engine whether execution may be continued or not.

no body is required on request. If async support has been negotiated using feature_get/set the status command may be sent while the debugger engine is in a 'run state'.

The status attribute values of the response may be:

  • starting: State prior to execution of any code
  • stopping: State after completion of code execution. This typically happens at the end of code execution, allowing the IDE to further interact with the debugger engine (for example, to collect performance data, or use other extended commands).
  • stopped: IDE is detached from process, no further interaction is possible.
  • running: code is currently executing. Note that this state would only be seen with async support turned on, otherwise the typical state during IDE/debugger interaction would be 'break'
  • break: code execution is paused, for whatever reason (see below), and the IDE/debugger can pass information back and forth.

The reason attribute value may be:

  • ok
  • error
  • aborted
  • exception
Returns
The id of the request.
virtual std::size_t zorba::DebuggerClient::step_into ( )
pure virtual

Send the step into command to the debug engine.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::step_out ( )
pure virtual

Send the step out command to the debug engine.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::step_over ( )
pure virtual

Send the step over command to the debug engine.

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::stop ( bool  withQuit)
pure virtual

Send the stop command to the debug engine.

This command tells the debug engine, that it should break the execution at the next point possible.

Parameters
withQuitThis is a Zorba extension of the DBGP protocol that controls if the client should terminate execution and quit (true) or only terminate execution but not quit (false). This is used by command line clients that implement multiple query runs.
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::stream_option ( OutputStream  aStream,
StreamBehaviour  aBehaviour 
)
pure virtual

Setting a stream option.

This method is used to tell the debug engine how to handle I/O. The debug engine either reads and writes from/to stdin/stdout or it can also copy it to the client or it can read/write everything from the client.

Parameters
aStreamSpecifies for which stream the option should be changed.
aBehaviourSpecifies which behaviour the debug client should have for reading/writing.
Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::typemap_get ( )
pure virtual

Get a mapping of types.

The IDE calls this command to get information on how to map language specific type names (as received in the property element returned by the context_get, and property_* commands). The debugger engine returns all data types that it supports. There may be multiple map elements with the same type attribute value, but the name value must be unique. This allows a language to map multiple language specific types into one of the common data types (eg. float and double can both be mapped to float).

Returns
The id of this request
virtual std::size_t zorba::DebuggerClient::variables ( )
pure virtual

Get the variables in all the contexts in the topmost stack frame.

Returns
The id of the request.

The documentation for this class was generated from the following file: