Make a Validator wait for the API to connect to it
We’ve just released new Wait For API functionality for all our Validators.
This article is going to explain the what, why and how. First, I’ll describe the problem being solved.
The Problem
The multiple Validator tools have an API allowing you to control the Validator from the program being monitored.
You can use the API to:
- connect to a running Validator
- launch a Validator then connect to it
- leave the API embedded in your release product with no cost to you (financial or performance) – it does nothing without the correct Validator installed on the same machine
These APIs are very useful but there is one thing you can’t do with them – start the Validator from the command line (for an automated test) and make the Validator wait for an API call to connect to the Validator.
The new API allows you to use the API when you are controlling the Validator from the command line and the Validator gets started first with the application being monitored being started separately from the Validator. This means the Validator must wait for the target program, something that until you couldn’t do with the command line if you were expecting the target program to connect via the API.
The solution
The solution comes in two parts.
- a new API to implement connect to Validator part of Wait For API
- command line options to configure the Validator user interface to use Wait For API
API
The new API is StartProfilerWaitForAPI. There is a version for each Validator:
| Bug Validator | bvStartProfilerWaitForAPI | Command line documentation | API documentation |
| Coverage Validator | cvStartProfilerWaitForAPI | Command line documentation | API documentation |
| Memory Validator | mvStartProfilerWaitForAPI | Command line documentation | API documentation |
| Performance Validator | pvStartProfilerWaitForAPI | Command line documentation | API documentation |
| Thread Validator | tvStartProfilerWaitForAPI | Command line documentation | API documentation |
- insistOnNoSessions TRUE: find a Validator that is not busy recording a session or post processing a session and that has not recorded any sessions.
FALSE: find any Validator that is not busy recording a session or post processing a session.
Recommended value: FALSE - waitTimeout How many seconds to wait while searching for a Validator. Recommended value: 60
- launchNewGUIIfTimeoutExpired) TRUE: launch a new Validator GUI if a Validator can’t be found.
FALSE: fail to connect to Validator if a Validator can’t be found.
Recommended value: FALSE
Command Line
There are two command line options for controlling Wait For API.
- -waitForAPI <process name> The process name should include the full path to the executable. If that path contains spaces, quote the path.
- -waitForAPITimeout <timeout in seconds> The timeout is specified in seconds. The timeout is optional. The default value is 60 seconds.
The Validator will wait for the specified timeout for the specified application to connect to it. If that doesn’t happen the Validator will close, ending the command line session.
If the API does connect to the Validator, the Validator will perform it’s normal profiling actions and carry out the various options specified on the command line.
Example Command Line
memoryValidator_x64.exe -hideUI -waitForAPI “c:\test with spaces\testWaitForAPI.exe” -saveSession “c:\test with spaces\testResults.mvm_x64”