zorba::DebuggerClient

#include <zorba/debugger_client.h>

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.

Public Types

BreakpointType

HitCondition

OutputStream

StreamBehaviour

Public Static Functions

DebuggerClient *

createDebuggerClient(DebuggerEventHandler *aHandler, unsigned short aPort, const std::string &aHost)

creates a new instance of a DebuggerClient implementation.

Public Functions

void

accept()=0

Waits for a debug engine to attach.

std::size_t

breakpoint_get(std::size_t aBreakpointId)=0

Get information about a breakpoint.

std::size_t

breakpoint_list()=0

Query all breakpoints.

std::size_t

breakpoint_remove(std::size_t aBreakpointId)=0

Remove a breakpoint.

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.

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.

std::size_t

context_get(int depth=-1, int contextId=-1)=0

Get the context at a given stack depth.

std::size_t

context_names(int depth=-1)=0

Get the context names at a given stack depth.

std::size_t

detach()=0

Send the detach command to the debug engine.

std::size_t

do_break()=0

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

std::size_t

eval(const std::string &aExpr)=0

Evaluates an expression.

std::size_t

feature_get(const std::string &aFeatureName)=0

Query the debug engine for supported features.

std::size_t

feature_set(const std::string &aFeatureName, const std::string &aValue)=0

Set a specific feature of the engine.

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.

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.

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.

void

quit()=0

Tells the client to quit.

std::size_t

run()=0

Send the run command to the debug engine.

std::size_t

source(const std::string &aFile, unsigned aBeginLine=0, unsigned aEndLine=0)=0

List the source code at a given position.

std::size_t

stack_depth()=0

Get the depth of the stack.

std::size_t

stack_get(int depth=-1)=0

Get information about the stack at a given depth.

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.

std::size_t

step_into()=0

Send the step into command to the debug engine.

std::size_t

step_out()=0

Send the step out command to the debug engine.

std::size_t

step_over()=0

Send the step over command to the debug engine.

std::size_t

stop(bool withQuit)=0

Send the stop command to the debug engine.

std::size_t

stream_option(OutputStream aStream, StreamBehaviour aBehaviour)=0

Setting a stream option.

std::size_t

typemap_get()=0

Get a mapping of types.

std::size_t

variables()=0

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

~DebuggerClient()

Public Types

BreakpointType

 BreakpointType

HitCondition

 HitCondition

OutputStream

 OutputStream

StreamBehaviour

 StreamBehaviour

Public Static Functions

createDebuggerClient

DebuggerClient * createDebuggerClient(DebuggerEventHandler *aHandler, unsigned short aPort, const std::string &aHost)

creates a new instance of a DebuggerClient implementation.

Parameters

aHandler The event handler, where answered should get delivered to.
aPort The port the client should listen to.
aHost the host the client should listen to

Returns

A DebuggerClient implementation.

Public Functions

accept

void accept()=0

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.

breakpoint_get

std::size_t breakpoint_get(std::size_t aBreakpointId)=0

Get information about a breakpoint.

Parameters

aBreakpointId The id of the breakpoint.

Returns

The id of this request

breakpoint_list

std::size_t breakpoint_list()=0

Query all breakpoints.

Returns

The id of this request

breakpoint_remove

std::size_t breakpoint_remove(std::size_t aBreakpointId)=0

Remove a breakpoint.

Parameters

aBreakpointId The id of the breakpoint.

Returns

The id of this request

breakpoint_set

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.

Parameters

aType The type of the breakpoint (line, call, return etc.).
aEnabled Should the breakpoint be enabled?
aLinenumber The line number where to set the breakpoint.
aFilename The file where a breakpoint should be set.
aFunctionName The name of the function where to break (only to be used if aType == Call || aType == Return)
aExceptionName The name of the exception to break (only to be used if aType == Exception)
hit_value A numeric value used together with the hit_condition to determine if the breakpoint should pause execution or be skipped.
aCondition The condition used together with 'hit_value' (default is '>=')
aIsTemporary Flag 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.
aExpression code 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

breakpoint_update

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.

Parameters

aBreakpointId The id of the breakpoint.
aEnabled Should the breakpoint be enabled?
aLinenumber The line number where to set the breakpoint.
hit_value A numeric value used together with the hit_condition to determine if the breakpoint should pause execution or be skipped.
aCondition The condition used together with 'hit_value' (default is '>=')

Returns

The id of this request

context_get

std::size_t context_get(int depth=-1, int contextId=-1)=0

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

depth The depth on which to quey (optional)
contextId The contextId (optional)

Returns

The id of this request

context_names

std::size_t context_names(int depth=-1)=0

Get the context names at a given stack depth.

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

Parameters

depth The depth on which to quey (optional)

Returns

The id of this request

detach

std::size_t detach()=0

Send the detach command to the debug engine.

Returns

The id of this request

do_break

std::size_t do_break()=0

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

Returns

The id of this request

eval

std::size_t eval(const std::string &aExpr)=0

Evaluates an expression.

Parameters

aExpr The expression to evaluate.

Returns

The id of this request

feature_get

std::size_t feature_get(const std::string &aFeatureName)=0

Query the debug engine for supported features.

Parameters

aFeatureName The 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

feature_set

std::size_t feature_set(const std::string &aFeatureName, const std::string &aValue)=0

Set a specific feature of the engine.

Parameters

aFeatureName The 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
aValue The value of the feature

Returns

The id of this request

property_get

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.

Parameters

aPropertyLongName roperty long name (required)
aStackDepth stack depth (optional)
aContextId The context id for which to query.
aMaxDataSize The maximal size of the data sent back from the debug engine.
aDatapage
aPropertyKey

Returns

The id of this request

property_set

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.

Parameters

aPropertyLongName roperty long name (required)
aStackDepth stack depth (optional)
aContextId The context id for which to query.
aMaxDataSize The maximal size of the data sent back from the debug engine.
aPropertyAddress property address as retrieved in a property element (optional).

Returns

The id of this request

property_value

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.

Parameters

aPropertyLongName roperty long name (required)
aStackDepth stack depth (optional)
aContextId The context id for which to query.
aMaxDataSize The maximal size of the data sent back from the debug engine.
aDatapage
aPropertyKey property key as retrieved in a property element (optional)
aPropertyAddress property address as retrieved in a property element (optional).

Returns

The id of this request

quit

void quit()=0

Tells the client to quit.

This method blocks until the client quit successfully.

run

std::size_t run()=0

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

source

std::size_t source(const std::string &aFile, unsigned aBeginLine=0, unsigned aEndLine=0)=0

List the source code at a given position.

Parameters

aFile The URI of the file the debug engine should deliver.
aBeginLine The starting point on which line the debug engine should start to read.
aEndLine The line number where the debug engine should stop reading from the file.

Returns

The id of this request.

stack_depth

std::size_t stack_depth()=0

Get the depth of the stack.

Returns

The id of this request

stack_get

std::size_t stack_get(int depth=-1)=0

Get information about the stack at a given depth.

Parameters

depth The depth on which to quey (optional)

Returns

The id of this request

status

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.

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.

step_into

std::size_t step_into()=0

Send the step into command to the debug engine.

Returns

The id of this request

step_out

std::size_t step_out()=0

Send the step out command to the debug engine.

Returns

The id of this request

step_over

std::size_t step_over()=0

Send the step over command to the debug engine.

Returns

The id of this request

stop

std::size_t stop(bool withQuit)=0

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

withQuit This 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

stream_option

std::size_t stream_option(OutputStream aStream, StreamBehaviour aBehaviour)=0

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

aStream Specifies for which stream the option should be changed.
aBehaviour Specifies which behaviour the debug client should have for reading/writing.

Returns

The id of this request

typemap_get

std::size_t typemap_get()=0

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

variables

std::size_t variables()=0

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

Returns

The id of the request.

~DebuggerClient

 ~DebuggerClient()