From GridLAB-D Wiki
Jump to: navigation, search

REQUIREMENT  Proposed for review  --Dchassin 14:09, 6 August 2012 (UTC)

Req:debug module - Debug module requirements

As of Hassayampa (Version 3.0) debugging is no longer supported directly in the core. Instead it is implemented by the debug module, which functions much like the assert module but provides a mechanism for users to input commands and alter the behavior of the debugging objects while the simulation is running. By default this user interface is the command line, but an API is provided to hook in graphical user interfaces as well.

Application Concept

The debug module allows modelers to include debugging object in models. Debugging objects allow inspection of properties and global while the simulation is running. Some illustrative examples are

Break on a global variable
The following illustrates stopping the simulation when the clock reaches a specified date and time
// Examples:debug_clock.glm
module debug {
  break "clock == '2001-01-01 00:00:00';
  action "prompt";
}
The following behavior occurs
host% gridlabd --debugger debug_clock.glm
DEBUG: break on clock == '2001-01-01 00:00:00';
DEBUG> quit

host%
 TODO:  provide more examples taken from integrated debugger

Definitions

Breakpoint 
A breakpoint defines a condition that causes the debugger to stop when the condition is satisfied.
Debug command 
A debug command is a command that is interpreted by a debug object.
Debug context 
The debug context determines the scope within which command are interpreted.
Debug object 
A debug object is an object that is capable of accepting debug commands.
Watchpoint 
A watchpoint defines a value that causes the debugger to stop when the value changes.

General requirements

R1

Activation
Objects defined in the debug module shall be active only when the global variable debug is set to a non-zero value.

R2

Context
Debug objects shall establish the context in which debug commands are interpreted.

R2.1

Global context
Debug object with no parent shall use the global context.

R2.2

Local context
Debug objects with a parent shall use the parent object's context.

R3

Breakpoints
Debug objects shall stop and accept commands when a breakpoint condition is satisfied.

R4

Watchpoints
Debug objects shall stop and accept commands when a watchpoint variable is modified.

Version

The debug module is supported as of Hassayampa (Version 3.0).

See also