Please enable JavaScript to view this site.

Thread Validator Help

Navigation: The User Interface > Settings > Global Settings > Data Collection

Thread Coverage

Scroll Prev Top Next More

 

The Thread Coverage tab allows you to control collection of coverage statistics for synchronization functions.

 

thread-coverage-settings

 

 

What is thread coverage?

 

Calculating thread coverage involves parsing your source code to determine all thread synchronization locations and then matching that data with information from the callstacks of each allocation in your session.

 

Some of these activities are time consuming, so the default is not to collect thread coverage statistics, but to let you optionally control the behaviour as below.

 

 

Controlling thread coverage data collection

 

Collect thread coverage data instructionStep enables the collection of thread coverage data

 

 The Coverage tab (example shown below) shows the thread coverage statistics for each file that contains thread synchronization statements. This allows you to check how well you're testing your thread synchronization code.

 

coverage-tab-example

 

 

 note See the section at the end of this page about tracking waitable handles.

 

 

When the collection of thread coverage data is enabled, the are some additional options to tune the performance.

 

Count visits to synchronization locations once instructionStep only count line visits once per line when this is selected (default)

 

Normally each line is counted just once (faster).

 

Although this option means they can be counted for all visits to each line, this will be noticeably slower for large applications.

 

 

Cache thread coverage data instructionStep enable caching of coverage statement information (default)

 

Calculating the coverage statements for each file can be time consuming, especially for large applications as it requires parsing the source code each time the application is run to determine where the thread synchronization locations are.

 

Caching the coverage statement information improves this by only recalculating it when the source code is modified.

 

 

Include 3rd party files in thread coverage statistics instructionStep include 3rd party files as specified in File Locations

 

For most activities you'll want to keep this option deselected.

 

 

Include files with no thread coverage statements in statistics instructionStep includes relevant source code files

 

Some source code files do not perform any thread synchronization operations. As such these files may be viewed as unwanted data on the coverage report, so the default is not to include these.

 

 

Include files that cannot be read in statistics instructionStep includes source code filenames referencing files that do not exist on your computer

 

Typically these are third party files in pre-built DLLs. By default they are not included in the statistics.

 

 

Clear Coverage Cache... instructionStep delete any existing thread coverage cache files stored on your computer

 

 

Thread coverage filters

 

Thread coverage calculation is quite likely to include some third party source files or header files that are out of your control, e.g. from STL, third party files in pre-built DLLs, etc.

 

There may also be some files that create waitable handles but which you know will never be used in a thread synchronization operation.

 

If you don't want results to include such files, you can specify a number of filters to exclude them.

 

Coverage filters need to be set before the session starts in order to affect results.

 

Configure Filters... instructionStep shows the Thread Coverage Filters dialog that lets you manage the list of filters...

 

thread-coverage-filter-settings

 

This dialog is the same one accessed via the local Filters button on the Coverage tab.

 

 

The Filters dialog has some basic controls for managing the filters:

 

Add... instructionStep adds a new filter, as in the example above
 

Edit... or double click an item in the list instructionStep opens the Thread Coverage Filter dialog to modify the enabled state, type or target of the selected filter item

 
 You can also enable/disable an item via the yellow checkbox on each item in the list.

 

Remove instructionStep deletes all selected filters in the list, or press b_del
 

Remove All instructionStep clears the list of filters

 

Enable All instructionStep sets all filters active
 

Disable All instructionStep sets all filters inactive (but does not remove them from the list)

 

Each filter can only be one of the three types: filename, directory or DLL. However, you can mix and match multiple filters of any type.

 

 

For example, to add a new filter:

 

Configure Filters... instructionStep Add... instructionStep choose a filter type filename, directory or DLL instructionStep Browse... (or enter a path directly) instructionStep choose a relevant item to add instructionStep OK instructionStep OK

 

thread-coverage-filter-browse-settings

 

 

To help recognise types of filters in the list, each item is prefixed by some bracketed flags as follows

 

[File] - file

[Dir] - directory

[DLL] - DLL

 

 

Thread coverage auto merge

 

Different runs of your application may execute different parts of your application, in which case you might want to merge the results of one run with the results of another.

 

Configure Auto Merge... instructionStep shows the Auto Merge dialog that lets you configure merging of thread coverage results

 

 thread-coverage-auto-merge-settings

 

The automatic merging works by merging the results of each individual thread coverage session into a central session.

 

The central session is stored on disk in a file you specify, or in a file using the name of the session, e.g. TestThis.exe would get saved in TestThis.tvm in the same directory as Thread Validator resides.

 

Enable auto-merging of thread coverage statistics instructionStep switches the merging feature on (default is off)

 

 

Depending on how many applications you are performing thread coverage on, you may want your thread coverage data to go to one central location or to a different location for each application under test.

 

Name of auto-merge session is based on the name of the application under test instructionStep saves the central session in a file named according to the application under test in this session (the default)

 

By default, the auto-merge session will be stored in the same directory as Thread Validator, but you can change this:

 

Directory for auto-merge session instructionStep saves the auto-merge session in the specified directory

 

For example, if you run the application nativeExample.exe, and specify a central session directory of e:\threadCoverageResults, the central session will be saved in a file named e:\threadCoverageResults\nativeExample.tvm.

 

Name of central session is specified instructionStep save the auto-merge session in a filename and path of your choice (enter or Browse... to a file)

 

 

Auto-merge session reset

 

The auto-merge results can be automatically cleared by certain triggers, or not cleared at all.

 

When performing thread coverage analysis sometimes you will uncover a bug in your software and need to modify the software, and/or run different executables. When this happens, line numbers and/or files often change, and you usually wouldn't want to merge thread coverage data from the modified software with existing coverage data.

 

The triggers for clearing the merged session results are:

 

When any source file is modified (the default)
 

When the application under test changes
 

No clearing of merged session results occurs under any circumstance

 

If you don't want an automatic trigger, there's also a manual trigger:

 

Clear Auto Merge Results instructionStep click to clear auto-merged results at any time of your choosing

 

 

 

Not tracking waitable handles?

 

If you choose to collect thread coverage data, and close the settings dialog (or switch to another settings page), you may get the following offer to improve coverage by tracking waitable handles.

 

not-tracking-waitable-handles

 

 

Yes instructionStep switches on the Hook Insertion setting for tracking functions working with waitable handles

 

If you haven't actually enabled any of the waitable handles, a warning will appear:

 

not-tracking-waitable-handles2

 

 

OK instructionStep displays the Hook Insertion settings to choose which waitable handles you want to track

 

Pick which waitable handle functions you're intertested in for coverage and click OK

 

hook-insertion-settings-d

 

Alternatively if you don't want to get coverage after all, Cancel and then uncheck Collect thread coverage data to prevent these warnings.

 

 

Reset All - Resets all global settings, not just those on the current page.

 

 

Reset - Resets the settings on the current page.