core/Debugger.hh

   1 /******************************************************************************
   2  * Copyright (c) 2000-2016 Ericsson Telecom AB
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *
  10  *   Baranyi, Botond – initial implementation
  11  *
  12  ******************************************************************************/
  13
  14 #ifndef DEBUGGER_HH
  15 #define DEBUGGER_HH
  16
  17 #include "Vector.hh"
  18 #include "Basetype.hh"
  19 #include "Charstring.hh"
  20 #ifdef TITAN_RUNTIME_2
  21 #include "RT2/PreGenRecordOf.hh"
  22 #else
  23 #include "RT1/PreGenRecordOf.hh"
  24 #endif
  25 #include <regex.h>
  26
  27 /** alias for record of charstring */
  28 typedef PreGenRecordOf::PREGEN__RECORD__OF__CHARSTRING charstring_list;
  29
  30 // debugger forward declarations
  31 class TTCN3_Debug_Scope;
  32 class TTCN3_Debug_Function;
  33
  34 // other forward declarations
  35 class Module_Param;
  36
  37
  38 //////////////////////////////////////////////////////
  39 ////////////////// TTCN3_Debugger ////////////////////
  40 //////////////////////////////////////////////////////
  41
  42 /** main debugger class
  43   *
  44   * instantiated once per process at the beginning of the current process,
  45   * destroyed at the end of the current process */
  46 class TTCN3_Debugger {
  47 public:
  48
  49   struct variable_t;
  50
  51   typedef CHARSTRING (*print_function_t)(const variable_t&);
  52   typedef boolean (*set_function_t)(variable_t&, Module_Param&);
  53
  54   /** type for keeping track of a variable */
  55   struct variable_t {
  56     /** pointer to the variable object, not owned */
  57     union {
  58       /** container for non-constant variable objects */
  59       void* value;
  60       /** container for constant variable objects */
  61       const void* cvalue;
  62     };
  63     /** variable name (used for looking up variables), not owned */
  64     const char* name;
  65     /** name of the variable's type, not owned */
  66     const char* type_name;
  67     /** name of the module the variable was declared in (only set for global
  68       * variables, otherwise NULL), not owned */
  69     const char* module;
  70     /** variable printing function (using the variable object's log() function) */
  71     print_function_t print_function;
  72     /** variable setting (overwriting) function (using the variable object's
  73       * set_param() function) - set to NULL for constant variables */
  74     set_function_t set_function;
  75   };
  76
  77   /** this type pairs a debug scope with a name, used for storing global and
  78     * component scopes */
  79   struct named_scope_t {
  80     /** scope name (module name for global scopes, or component type name for
  81       * component scopes), not owned */
  82     const char* name;
  83     /** scope pointer, owned */
  84     TTCN3_Debug_Scope* scope;
  85   };
  86
  87   /** type for storing a function call in the call stack */
  88   struct function_call_t {
  89     /** pointer to the debug function object */
  90     TTCN3_Debug_Function* function;
  91     /** TTCN-3 line number, where the function was called from */
  92     int caller_line;
  93   };
  94
  95   /** type for storing breakpoints */
  96   struct breakpoint_t {
  97     /** module name, owned */
  98     char* module;
  99     /** line number */
 100     int line;
 101     /** batch file to be executed when the breakpoint is reached (optional) */
 102     char* batch_file;
 103   };
 104
 105   /** special breakpoint types, passed to breakpoint_entry() as the line parameter,
 106     * so these need to be 0 or negative, to never conflict with any line number */
 107   enum special_breakpoint_t {
 108     /** triggered when the local verdict is set to ERROR (by dynamic test case errors) */
 109     SBP_ERROR_VERDICT = 0,
 110     /** triggered when the local verdict is set to FAIL (by the user) */
 111     SBP_FAIL_VERDICT = -1
 112   };
 113
 114   /** type for storing the settings of automatic breakpoints */
 115   struct automatic_breakpoint_behavior_t {
 116     /** indicates whether the breakpoint should be triggered by the associated event */
 117     bool trigger;
 118     /** batch file to be executed if the breakpoint is triggered (optional) */
 119     char* batch_file;
 120   };
 121
 122   /** stepping type */
 123   enum stepping_t {
 124     NOT_STEPPING,
 125     STEP_OVER,
 126     STEP_INTO,
 127     STEP_OUT
 128   };
 129
 130 private:
 131
 132   /** indicates whether the debugger has been activated, meaning that the debugger's
 133     * command line option (-n) was used during the build (switched automatically
 134     * by generated code) */
 135   bool enabled;
 136
 137   /** the debugger's on/off switch (switched by the user) */
 138   bool active;
 139
 140   /** true if test execution has been halted (by a breakpoint or by the user) */
 141   bool halted;
 142
 143   /** the debugger's output file handler (NULL if the debugger's output is only
 144     * sent to the console) */
 145   FILE* output_file;
 146
 147   /** name of the debugger's output file (NULL if the debugger's output is only
 148     * sent to the console) */
 149   char* output_file_name;
 150
 151   /** indicates whether the debugger's output should be sent to the console */
 152   bool send_to_console;
 153
 154   /** list of all global and component variables, elements are owned */
 155   Vector<variable_t*> variables;
 156
 157   /** list of global scopes */
 158   Vector<named_scope_t> global_scopes;
 159
 160   /** list of component scopes */
 161   Vector<named_scope_t> component_scopes;
 162
 163   /** pointers to debug function objects and the lines they were called from
 164     * (resembling a call stack), the current function is always the last element
 165     * in the array (the top element in the stack) */
 166   Vector<function_call_t> call_stack;
 167
 168   /** list of breakpoints */
 169   Vector<breakpoint_t> breakpoints;
 170
 171   /** string containing function call snapshots, owned */
 172   char* snapshots;
 173
 174   /** stores the last line hit by breakpoint_entry() */
 175   breakpoint_t last_breakpoint_entry;
 176
 177   /** current stack level (reset when test execution is halted or resumed) */
 178   int stack_level;
 179
 180   /** automatic breakpoint triggered by setting the local verdict to FAIL */
 181   automatic_breakpoint_behavior_t fail_behavior;
 182
 183   /** automatic breakpoint triggered by setting the local verdict to ERROR */
 184   automatic_breakpoint_behavior_t error_behavior;
 185
 186   /** batch file executed automatically when test execution is halted
 187     * NULL if switched off
 188     * is overridden by breakpoint-specific batch files */
 189   char* global_batch_file;
 190
 191   /** result of the currently executing command */
 192   char* command_result;
 193
 194   /** result of the last D_LIST_VARIABLES command */
 195   char* last_variable_list;
 196
 197   /** stores which stepping option was requested by the user (if any) */
 198   stepping_t stepping_type;
 199
 200   /** stores the size of the call stack when the last stepping operation was
 201     * initiated */
 202   size_t stepping_stack_size;
 203
 204   /** temporary breakpoint set by the 'run to cursor' operation */
 205   breakpoint_t temporary_breakpoint;
 206
 207   /** true if an 'exit all' command was issued
 208     * switched to false when test execution is restarted */
 209   bool exiting;
 210
 211   /** test execution is automatically halted at start if set to true */
 212   bool halt_at_start;
 213
 214   /** batch file executed automatically at the start of test execution
 215     * if not set to NULL (not owned) */
 216   const char* initial_batch_file;
 217
 218   //////////////////////////////////////////////////////
 219   ///////////////// internal functions /////////////////
 220   //////////////////////////////////////////////////////
 221
 222   /** switches the debugger on or off
 223     * handles the D_SWITCH command */
 224   void switch_state(const char* p_state_str);
 225
 226   /** adds a new breakpoint at the specified module and line with the specified
 227     * batch file (if not NULL), or changes the batch file of an existing
 228     * breakpoint
 229     * handles the D_SET_BREAKPOINT command */
 230   void set_breakpoint(const char* p_module, int p_line, const char* batch_file);
 231
 232   /** removes the breakpoint from the specified module/line, if it exists
 233     * can also be used to remove all breakpoints from the specified module or
 234     * all breakpoints in all modules
 235     * handles the D_REMOVE_BREAKPOINT command */
 236   void remove_breakpoint(const char* p_module, const char* p_line);
 237
 238   /** switches an automatic breakpoint related to the specified event on or off
 239     * and/or sets the batch file to run when the breakpoint is triggered
 240     * @param p_event_str string representation of the event that triggers the
 241     * breakpoint (either "error" or "fail")
 242     * @param p_state_str "on" or "off", indicates the new state of the breakpoint
 243     * @param p_batch_file name of the batch file to execute (NULL means don't
 244     * execute anything)
 245     * handles the D_SET_AUTOMATIC_BREAKPOINT command */
 246   void set_automatic_breakpoint(const char* p_event_str, const char* p_state_str,
 247     const char* p_batch_file);
 248
 249   /** prints the debugger's settings
 250     * handles the D_PRINT_SETTINGS command */
 251   void print_settings();
 252
 253   /** prints the current call stack
 254     * handles the D_PRINT_CALL_STACK command */
 255   void print_call_stack();
 256
 257   /** sets the current stack level to the specified value
 258     * handles the D_SET_STACK_LEVEL command */
 259   void set_stack_level(int new_level);
 260
 261   /** finds the variable with the specified name, and prints its value or an
 262     * error message
 263     * the variable's value is printed using its log() function
 264     * handles (one parameter of) the D_PRINT_VARIABLE command */
 265   void print_variable(const char* p_var_name);
 266
 267   /** finds the variable with the specified name, and overwrites its value or
 268     * displays an error message
 269     * the new value is received in a string array; this is concatenated into one
 270     * string (with one space separating each string element); then it is passed
 271     * to the module parameter parser, which creates a Module_Param object from it
 272     * (if its syntax is correct)
 273     * the variable's value is overwritten by passing the Module_Param object to
 274     * its set_param() function
 275     * handles the D_OVERWRITE_VARIABLE command */
 276   void overwrite_variable(const char* p_var_name, int p_value_element_count,
 277     char** p_value_elements);
 278
 279   /** sets the debugger's output to the console and/or a text file
 280     * handles the D_SET_OUTPUT command
 281     * @param p_output_type "console", "file" or "both"
 282     * @param p_file_name output file name or NULL */
 283   void set_output(const char* p_output_type, const char* p_file_name);
 284
 285   /** switches the global batch file on or off
 286     * handles the D_SET_GLOBAL_BATCH_FILE command */
 287   void set_global_batch_file(const char* p_state_str, const char* p_file_name);
 288
 289   /** resumes execution until the next breakpoint entry (in the stack levels
 290     * specified by the stepping type arguments) is reached (or until test execution
 291     * is halted for any other reason)
 292     * handles the D_STEP_OVER, D_STEP_INTO and D_STEP_OUT commands */
 293   void step(stepping_t p_stepping_type);
 294
 295   /** resumes execution until the specified location is reached
 296     * (or until test execution is halted for any other reason)
 297     * handles the D_RUN_TO_CURSOR command */
 298   void run_to_cursor(const char* p_module, int p_line);
 299
 300   /** halts test execution, processing only debug commands
 301     * @param p_batch_file batch file executed after the halt (if not NULL)
 302     * @param p_run_global_batch indicates whether the global batch file should
 303     * be executed after the halt (only if p_batch_file is NULL)
 304     * handles the D_HALT command */
 305   void halt(const char* p_batch_file, bool p_run_global_batch);
 306
 307   /** resumes the halted test execution
 308     * handles the D_CONTINUE command */
 309   void resume();
 310
 311   /** exits the current test or the execution of all tests
 312     * handles the D_EXIT command */
 313   void exit_(const char* p_what);
 314
 315   /** returns the index of the specified breakpoint, if found,
 316     * otherwise returns breakpoints.size() */
 317   size_t find_breakpoint(const char* p_module, int p_line) const;
 318
 319   /** returns the specified variable, if found, otherwise returns NULL */
 320   TTCN3_Debugger::variable_t* find_variable(const void* p_value) const;
 321
 322   /** handles metacharacters in the specified file name skeleton
 323     * @return final file name (must be freed by caller) */
 324   static char* finalize_file_name(const char* p_file_name_skeleton);
 325
 326   /** initialization function, called when the first function is added to the
 327     * call stack */
 328   void test_execution_started();
 329
 330   /** clean up function, called when the last function is removed from the
 331     * call stack */
 332   void test_execution_finished();
 333
 334 public:
 335   /** constructor - called once per process (at the beginning) */
 336   TTCN3_Debugger();
 337
 338   /** destructor - called once per process (at the end) */
 339   ~TTCN3_Debugger();
 340
 341   //////////////////////////////////////////////////////
 342   ////// methods called from TITAN generated code //////
 343   //////////////////////////////////////////////////////
 344
 345   /** activates the debugger */
 346   void activate() { enabled = true; }
 347
 348   /** creates, stores and returns a new global scope for the specified module
 349     * (this scope contains all global variables visible in the module) */
 350   TTCN3_Debug_Scope* add_global_scope(const char* p_module);
 351
 352   /** creates, stores and returns a new component scope for the specified component
 353     * type (this scope contains all variables declared in the component type) */
 354   TTCN3_Debug_Scope* add_component_scope(const char* p_component);
 355
 356   /** stores the string representation of the current function's return value
 357     * (only if the debugger is switched on) */
 358   void set_return_value(const CHARSTRING& p_value);
 359
 360   /** activates a breakpoint if the specified line and the current function's module
 361     * match any of the breakpoints stored in the debugger
 362     * the special parameter values (SBP_ERROR_VERDICT and SBP_FAIL_VERDICT) only
 363     * trigger a breakpoint if their respective behaviors have been set to do so
 364     * (does nothing if the debugger is switched off) */
 365   void breakpoint_entry(int p_line);
 366
 367   /** variable printing function for base types */
 368   static CHARSTRING print_base_var(const variable_t& p_var);
 369
 370   /** variable setting function for base types */
 371   static boolean set_base_var(variable_t& p_var, Module_Param& p_new_value);
 372
 373   /** variable printing function for value arrays */
 374   template <typename T_type, unsigned int array_size, int index_offset>
 375   static CHARSTRING print_value_array(const variable_t& p_var)
 376   {
 377     const void* ptr = p_var.set_function != NULL ? p_var.value : p_var.cvalue;
 378     TTCN_Logger::begin_event_log2str();
 379     ((VALUE_ARRAY<T_type, array_size, index_offset>*)ptr)->log();
 380     return TTCN_Logger::end_event_log2str();
 381   }
 382
 383   /** variable setting function for value arrays */
 384   template <typename T_type, unsigned int array_size, int index_offset>
 385   static boolean set_value_array(variable_t& p_var, Module_Param& p_new_value)
 386   {
 387     ((VALUE_ARRAY<T_type, array_size, index_offset>*)p_var.value)->set_param(p_new_value);
 388     return TRUE;
 389   }
 390
 391   /** variable printing function for template arrays */
 392   template <typename T_value_type, typename T_template_type,
 393     unsigned int array_size, int index_offset>
 394   static CHARSTRING print_template_array(const variable_t& p_var)
 395   {
 396     const void* ptr = p_var.set_function != NULL ? p_var.value : p_var.cvalue;
 397     TTCN_Logger::begin_event_log2str();
 398     ((TEMPLATE_ARRAY<T_value_type, T_template_type, array_size,
 399       index_offset>*)ptr)->log();
 400     return TTCN_Logger::end_event_log2str();
 401   }
 402
 403   /** variable setting function for template arrays */
 404   template <typename T_value_type, typename T_template_type,
 405     unsigned int array_size, int index_offset>
 406   static boolean set_template_array(variable_t& p_var, Module_Param& p_new_value)
 407   {
 408     ((TEMPLATE_ARRAY<T_value_type, T_template_type, array_size,
 409       index_offset>*)p_var.value)->set_param(p_new_value);
 410     return TRUE;
 411   }
 412
 413   /** variable printing function for port arrays */
 414   template <typename T_type, unsigned int array_size, int index_offset>
 415   static CHARSTRING print_port_array(const variable_t& p_var)
 416   {
 417     const void* ptr = p_var.set_function != NULL ? p_var.value : p_var.cvalue;
 418     TTCN_Logger::begin_event_log2str();
 419     ((PORT_ARRAY<T_type, array_size, index_offset>*)ptr)->log();
 420     return TTCN_Logger::end_event_log2str();
 421   }
 422
 423   /** variable printing function for timer arrays */
 424   template <typename T_type, unsigned int array_size, int index_offset>
 425   static CHARSTRING print_timer_array(const variable_t& p_var)
 426   {
 427     const void* ptr = p_var.set_function != NULL ? p_var.value : p_var.cvalue;
 428     TTCN_Logger::begin_event_log2str();
 429     ((TIMER_ARRAY<T_type, array_size, index_offset>*)ptr)->log();
 430     return TTCN_Logger::end_event_log2str();
 431   }
 432
 433   /** variable printing function for lazy parameters */
 434   template <typename EXPR_TYPE>
 435   static CHARSTRING print_lazy_param(const variable_t& p_var)
 436   {
 437     const void* ptr = p_var.set_function != NULL ? p_var.value : p_var.cvalue;
 438     TTCN_Logger::begin_event_log2str();
 439     ((Lazy_Param<EXPR_TYPE>*)ptr)->log();
 440     return TTCN_Logger::end_event_log2str();
 441   }
 442
 443   //////////////////////////////////////////////////////
 444   ////// methods called by other debugger classes //////
 445   //////////////////////////////////////////////////////
 446
 447   /** returns true if the debugger is activated (through the compiler switch) */
 448   bool is_activated() const { return enabled; }
 449
 450   /** returns true if the debugger is switched on */
 451   bool is_on() const { return active; }
 452
 453   /** returns true if test execution has been halted by the debugger */
 454   bool is_halted() const { return halted; }
 455
 456   /** prints the formatted string to the console and/or output file
 457     * (used for printing notifications or error messages) */
 458   void print(int return_type, const char* fmt, ...) const;
 459
 460   /** adds the formatted string to the currently executed command's result string */
 461   void add_to_result(const char* fmt, ...);
 462
 463   /** adds the specified function object pointer to the call stack
 464     * (only if the debugger is switched on) */
 465   void add_function(TTCN3_Debug_Function* p_function);
 466
 467   /** adds the specified scope object pointer to the current function's scope list
 468     * (only if the debugger is switched on and the call stack is not empty) */
 469   void add_scope(TTCN3_Debug_Scope* p_scope);
 470
 471   /** removes the specified function object pointer from the call stack, if it is
 472     * the function at the top of the stack */
 473   void remove_function(TTCN3_Debug_Function* p_function);
 474
 475   /** removes the specified scope object pointer from the current function's scope list
 476     * (only if the call stack is not empty) */
 477   void remove_scope(TTCN3_Debug_Scope* p_scope);
 478
 479   /** finds or creates, and returns the constant variable entry specified by
 480     * the parameters
 481     *
 482     * if the call stack is empty, an entry for a global or component variable is
 483     * created and stored in the main debugger object (if it doesn't already exist);
 484     * if the call stack is not empty (and if the debugger is switched on), the
 485     * variable entry for a local variable is created and stored by the current function */
 486   variable_t* add_variable(const void* p_value, const char* p_name, const char* p_type,
 487     const char* p_module, print_function_t p_print_function);
 488
 489   /** same as before, but for non-constant variables */
 490   variable_t* add_variable(void* p_value, const char* p_name, const char* p_type,
 491     const char* p_module, print_function_t p_print_function,
 492     set_function_t p_set_function);
 493
 494   /** removes the variable entry for the specified local variable in the current
 495     * function (only if the call stack is not empty) */
 496   void remove_variable(const variable_t* p_var);
 497
 498   /** returns the global scope object associated with the specified module */
 499   const TTCN3_Debug_Scope* get_global_scope(const char* p_module) const;
 500
 501   /** returns the component scope object associated with the specified component type */
 502   const TTCN3_Debug_Scope* get_component_scope(const char* p_component) const;
 503
 504   /** appends the specified function call snapshot to the end of the snapshot string */
 505   void add_snapshot(const char* p_snapshot);
 506
 507   /** executes a command received from the user interface */
 508   void execute_command(int p_command, int p_argument_count, char** p_arguments);
 509
 510   /** opens the debugger's output file for writing (if one has been set, but not
 511     * opened, in the HC process) */
 512   void open_output_file();
 513
 514   /** indicates whether an 'exit all' command has been issued
 515     * (this causes the execution of tests in the current queue to stop) */
 516   bool is_exiting() const { return exiting; }
 517
 518   /** sets the debugger to halt test execution at start (only in single mode) */
 519   void set_halt_at_start() { halt_at_start = true; }
 520
 521   /** sets the specified batch file to be executed at the start of test execution
 522     * (only in single mode) */
 523   void set_initial_batch_file(const char* p_batch_file) {
 524     initial_batch_file = p_batch_file;
 525   }
 526 };
 527
 528 /** the main debugger object */
 529 extern TTCN3_Debugger ttcn3_debugger;
 530
 531
 532 //////////////////////////////////////////////////////
 533 //////////////// TTCN3_Debug_Scope ///////////////////
 534 //////////////////////////////////////////////////////
 535
 536 /** debugger scope class
 537   *
 538   * instantiated at the beginning of every code block in the TTCN-3 code (except
 539   * for the code blocks of functions), plus one (global scope) instance is created
 540   * for every module and one (component scope) for every component type
 541   *
 542   * the class' main purpose is to track which local variables were created in the
 543   * current code block or to track which of the main debugger object's variables
 544   * belong to which global or component scope */
 545 class TTCN3_Debug_Scope {
 546
 547   /** list of pointers to local variable entries from the current function object or
 548     * global or component variable entries from the main debugger object
 549     * (the elements are not owned)*/
 550   Vector<TTCN3_Debugger::variable_t*> variables;
 551
 552 public:
 553
 554   /** constructor - lets the current function know of this new scope */
 555   TTCN3_Debug_Scope();
 556
 557   /** destructor - tells the current function to delete the variable entries listed
 558     * in this instance */
 559   ~TTCN3_Debug_Scope();
 560
 561   //////////////////////////////////////////////////////
 562   ////// methods called from TITAN generated code //////
 563   //////////////////////////////////////////////////////
 564
 565   /** passes the parameters to the main debugger or current function object to
 566     * create and store a (constant) variable entry from them, and tracks this new
 567     * variable by storing a pointer to it
 568     * (local variables are only created and stored if the debugger is switched on) */
 569   void add_variable(const void* p_value, const char* p_name, const char* p_type,
 570     const char* p_module, TTCN3_Debugger::print_function_t p_print_function);
 571
 572   /** same as before, but for non-constant variables */
 573   void add_variable(void* p_value, const char* p_name, const char* p_type,
 574     const char* p_module, TTCN3_Debugger::print_function_t p_print_function,
 575     TTCN3_Debugger::set_function_t p_set_function);
 576
 577   //////////////////////////////////////////////////////
 578   ////// methods called by other debugger classes //////
 579   //////////////////////////////////////////////////////
 580
 581   /** returns true if there is at least one variable in the scope object */
 582   bool has_variables() const { return !variables.empty(); }
 583
 584   /** returns the specified variable, if found, otherwise returns NULL
 585     * (the name searched for can also be prefixed with the module name in
 586     * case of global variables) */
 587   TTCN3_Debugger::variable_t* find_variable(const char* p_name) const;
 588
 589   /** prints the names of variables in this scope that match the specified;
 590     * names of imported global variables are prefixed with their module's name
 591     * @param p_posix_regexp the pattern converted into a POSIX regex structure
 592     * @param p_first true if no variables have been printed yet
 593     * @param p_module name of the current module, if it's a global scope,
 594     * otherwise NULL */
 595   void list_variables(regex_t* p_posix_regexp, bool& p_first,
 596     const char* p_module) const;
 597 };
 598
 599
 600 //////////////////////////////////////////////////////
 601 /////////////// TTCN3_Debug_Function /////////////////
 602 //////////////////////////////////////////////////////
 603
 604 /** debugger function class
 605   *
 606   * instantiated at the beginning of every function, destroyed when function execution ends
 607   *
 608   * tracks all variables created during the function's execution (local variables),
 609   * including the function's parameters, and stores the function's return value */
 610 class TTCN3_Debug_Function {
 611
 612   /** name of the function, not owned */
 613   const char* function_name;
 614
 615   /** the TTCN-3 keyword(s) used to define the function ("function", "testcase",
 616     * "altstep", "template" or "external function"), not owned */
 617   const char* function_type;
 618
 619   /** name of the module this function is defined in, not owned */
 620   const char* module_name;
 621
 622   /** names of the function's parameters (in the order of their declaration), owned */
 623   charstring_list* parameter_names;
 624
 625   /** types (directions) of the function's parameters ("in", "inout" or "out"), owned */
 626   charstring_list* parameter_types;
 627
 628   /** list of local variables tracked by this object, the array elements are owned */
 629   Vector<TTCN3_Debugger::variable_t*> variables;
 630
 631   /** list of pointers to the scope objects of code blocks in the function,
 632     * the elements are not owned
 633     * (currently not used for anything) */
 634   Vector<TTCN3_Debug_Scope*> scopes;
 635
 636   /** pointer to the global scope object, not owned
 637     * (may be NULL, if the module's global scope is empty) */
 638   const TTCN3_Debug_Scope* global_scope;
 639
 640   /** pointer to the runs-on component's scope object, not owned
 641     * (may be NULL, if the component's scope is empty or if the function has no runs-on clause) */
 642   const TTCN3_Debug_Scope* component_scope;
 643
 644   /** the function's return value (unbound if the return value has not been set yet,
 645     * or if the function doesn't return anything)
 646     *
 647     * since this is only set right before the function ends, it is only accessible
 648     * from the destructor */
 649   CHARSTRING return_value;
 650
 651 public:
 652
 653   /** constructor - initializes the instance with the specified parameters,
 654     * retrieves the global scope and component scope from the main debugger object */
 655   TTCN3_Debug_Function(const char* p_name, const char* p_type, const char* p_module,
 656     const charstring_list& p_parameter_names, const charstring_list& p_parameter_types, const char* p_component_name);
 657
 658   /** destructor - frees resources and saves the function's ending snapshot
 659     * (including the values of 'out' and 'inout' parameters and the return value)
 660     * in the main debugger object (only if the debugger is switched on) */
 661   ~TTCN3_Debug_Function();
 662
 663   //////////////////////////////////////////////////////
 664   ////// methods called from TITAN generated code //////
 665   //////////////////////////////////////////////////////
 666
 667   /** creates, stores and returns the variable entry of the local (constant) variable
 668     * specified by the parameters (only if the debugger is switched on) */
 669   TTCN3_Debugger::variable_t* add_variable(const void* p_value, const char* p_name,
 670     const char* p_type, const char* p_module,
 671     TTCN3_Debugger::print_function_t p_print_function);
 672
 673   /** same as before, but for non-constant variables */
 674   TTCN3_Debugger::variable_t* add_variable(void* p_value, const char* p_name,
 675     const char* p_type, const char* p_module,
 676     TTCN3_Debugger::print_function_t p_print_function,
 677     TTCN3_Debugger::set_function_t p_set_function);
 678
 679   /** stores the string representation of the value returned by the function */
 680   void set_return_value(const CHARSTRING& p_value);
 681
 682   /** saves the function's initial snapshot (including the values of 'in' and
 683     * 'inout' parameters) in the main debugger object
 684     * (only if the debugger is switched on) */
 685   void initial_snapshot() const;
 686
 687   //////////////////////////////////////////////////////
 688   ////// methods called by other debugger classes //////
 689   //////////////////////////////////////////////////////
 690
 691   /** adds the specified scope object pointer to the function's scope list */
 692   void add_scope(TTCN3_Debug_Scope* p_scope);
 693
 694   /** removes the specified scope object pointer from the function's scope list,
 695     * if it is the last scope in the list */
 696   void remove_scope(TTCN3_Debug_Scope* p_scope);
 697
 698   /** removes the specified variable from the variable list */
 699   void remove_variable(const TTCN3_Debugger::variable_t* p_var);
 700
 701   /** searches for the variable entry with the specified name in the function's
 702     * local variable list, the global scope (if any) and the component scope (if any),
 703     * returns NULL, if the variable was not found */
 704   TTCN3_Debugger::variable_t* find_variable(const char* p_name) const;
 705
 706   /** prints the function's type, name and current values of parameters */
 707   void print_function() const;
 708
 709   /** returns the name of the module the function was defined in */
 710   const char* get_module_name() const { return module_name; }
 711
 712   /** prints the names of variables specified by the parameters (separated by spaces)
 713     * handles the D_LIST_VARIABLES debugger command
 714     * @param p_scope specifies which scope to print variables from:
 715     * - "local" - the function's local variables (including variables in code blocks)
 716     * - "global" - variables in the module's global scope
 717     * - "comp" or "component" - variables in the function's runs-on component scope
 718     * - "all" - all variables visible in the function (i.e. all of the above)
 719     * @param p_filter a pattern to filter variable names further */
 720   void list_variables(const char* p_scope, const char* p_filter) const;
 721
 722   /** returns true if this instance belongs to a control part */
 723   bool is_control_part() const;
 724
 725   /** returns true if this instance belongs to a test case */
 726   bool is_test_case() const;
 727 };
 728
 729 /** This macro stores a function's return value in the current function.
 730   * The returned value might be an expression, so it is copied to a temporary first,
 731   * to avoid being evaluated twice. */
 732 #define DEBUGGER_STORE_RETURN_VALUE(tmp, ret_val) \
 733   (tmp = (ret_val), \
 734    ttcn3_debugger.set_return_value((TTCN_Logger::begin_event_log2str(), \
 735                                     tmp.log(), \
 736                                     TTCN_Logger::end_event_log2str())), \
 737    tmp)
 738
 739 #endif /* DEBUGGER_HH */
 740