vetuner

Last modified: 24.09.01 10:50

Table of Contents
1. General issues
2. Synopsis
3. GUI
3.1. Introduction
3.2. General properties
3.2.1. Garbage collection
3.2.2. Exception trace log file
3.2.3. Profiler output
3.3. Debug keys
3.4. Classes and routines
3.5. Heap

1. General issues

vetuner is a utility for operative changing (tuning) behavior of the program compiled by Visual Eiffel. For example, it is possible to:

vetuner connects to the selected file, which may be an executable or a DLL produced by Visual Eiffel, changes some run-time-specific data inside the file and writes results back to the disk. When the file is executed, the Eiffel run-time reads all the changes and uses them instead of default settings. As a result the program behavior is changed.

The settings that might be changed depend on several parameters, including compilation flags and run-time implementation. The table below summarizes the dependencies. To control some specific setting, the corresponding conditions should be met. For example, the application cannot be traced unless it is assembled with assertions generation turned on.

Table 1. Application settings dependencies

Category Application settings Compilation flags Granularity
Eiffel Assertions checks assertions on class
Debug instructions debug_instructions on instruction
Trace Exception trace log file - system
Execution trace assertions on feature
Optimization Execution profiling assertions on feature
Memory management - system

2. Synopsis

vetuner [-c] [-help] [-trace:[class_name,...]] [-xcp:[[store|overwrite|trace],...]] [-zone_Z_committed:N] [-zone_Z_reserved:N] [-zone_Z_size:N] [module_name]

Description

-c

run in batch mode: change the supplied module accordingly to the other options and exit

Note: All other options has no effect unless this one is specified

-help

display help

-trace:[class_name,...]

turn on the trace for all features of the given classes

-xcp:[[store|overwrite|trace],...]

change exception trace log file (.XCP) generation:

store always write the file, even when all exceptions are caught
overwrite create new the file for every run
trace write call stack trace together with exception information
-zone_Z_committed:N

set the committed memory (i.e., allocated physical storage) size of the zone Z to the value N (in bytes)

-zone_Z_reserved:N

set the reserved memory (i.e., virtual address space) size of the zone Z to the value N (in bytes)

-zone_Z_size:N

set the block (i.e., maximal Eiffel object) size in the zone Z to the valueN (in bytes). This value cannot be below 4 bytes and zones with higher number should have bigger block size. The block size for for the last two zones cannot be adjusted, because they are reserved for big objects, arrays and strings.

module_name

use the given name as a name of the executable or DLL module to be tuned

Note: Z is the number of memory region allocated by the memory manager. It should be in the range 1-12.


3. GUI

3.1. Introduction

When vetuner is started in interactive mode, it allows to view and modify application settings in a window mode. The main window includes several property pages, described in the sections below. Every property page can be modified independently. When all the changes are done, user can select which of them should be reflected in the application module by checking an appropriate check box for the corresponding property page.

Some property pages are available only when the application was assembled with proper options (see Application settings dependencies). Otherwise they might be disabled or absent.

The module to be tuned is taken either from the command line or specified after pressing Connect button. Only applications assembled by Visual Eiffel are subject for tuning. An attempt to connect to other modules causes vetuner to display the corresponding error message and to reject the modules.

vetuner detects the license which was used to assemble the application and displays it if the license imposes any limitations on the application in run-time (e.g., no garbage collection). Check the license to see the exact set of run-time limitations.


3.2. General properties

General properties affect the behaviour of the application as a whole.


3.2.1. Garbage collection

Memory manager relies on the following two values to determine when garbage collector should be started and how to allocate memory if garbage collected memory is not enough for newly created objects:

threshold

the initial total allocated memory size (in bytes) when garbage collector is started; garbage collector is not started while the total allocated memory size is below the given one

This value might be incremented by threshold delta in run-time. The increment might be performed several times. The value is never decremented in the current implementation.

threshold delta

the amount of memory (in bytes) to be used to increment threshold when garbage collector fails to release memory which is enough to keep newly created object

This value is constant in run-time in the current implementation.


3.2.2. Exception trace log file

This page allows to control the creation and content of the exception trace log file. See the corresponding command line option for details.


3.2.3. Profiler output

This page allows to specify the output format of the profiler. It does not specify whether the profiler is activated or not.

The formal is controlled by the two parameters:

Output

The fields to be output in the profiler log file

Sort

The field to be used as a sorting criteria to sort the lines in the profiler output

The table below describes the information fields that might be stored in the profiler log file.

Table 2. Profiler log file fields

Field name Description
Count Total number of times the routine was called
Time Total time spent in the routine, including the time spent in child routines
Ind time Total time spent in the routine, excluding the time spent in child routines
GC count Total number of times garbage collector was called
GC time Total time spent by garbage collector
Arr GC count Total number of times garbage collector was called for array-like objects (i.e., ARRAY and STRING areas)
Arr GC time Total time spent by garbage collector to handle array-like objects

3.3. Debug keys

The checked debug keys force all the corresponding debug instructions to be executable and the code enclosed in them is executed as any other Eiffel code. Otherwise, the debug instruction is considered inactive and is not executed.

Note: Debug keys could be also activated when the program starts by specifying their names just after a special option: -![debug_key,...] This option should be the first argument of the program. Multiple debug keys are allowed though they should be delimited by commas without any whitespace:

test -!debug1,debug2

It's impossible to specify the debug keys in such a way for DLLs. vetuner should be used instead.


3.4. Classes and routines

The settings for the classes included in the system might be configured on either all at once or per-class basis. All-at-once mode is achieved by pressind Set All/Clear All buttons. The buttons change their name after a press to the opposite one, reflecting which action is to be performed next time they are pressed.

The settings for a class might be configured by selecting the appropriate class name and pressing the button View. Now class-specific options might be set. The class settings also include feature settings and allow the same kind of control on all-at-once or per-feature basis. The settings for a specific routine might be configured by selecting an appropriate routine in the list of available routines and by pressing the button View.

To check what settings act on the class level and what act on the feature level, see Application settings dependencies.


3.5. Heap

The properties of the heap zone can be adjusted by pressing the Edit button. The properties are loosely coupled with the corresponding command line options. It is also possible to revert to the default heap settings if required.