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