TimedExec
[Helper Applications]
Win32 console application "TimedExec.exe" allows the controlled execution of an other executable X within a limited time period. Executable and time interval are specified as command line args. More...
|
Win32 console application "TimedExec.exe" allows the controlled execution of an other executable X within a limited time period. Executable and time interval are specified as command line args.
TimedExec starts X and waits until X has terminated or a configurable timeout has elapsed. If the timeout has elapsed it is assumed that process X has some malfunction and X will be killed via TerminateProcess(). This error and other problems when starting X are signalled with an exit code of 1.
If X terminates regularly its exit code will be used as exit code for TimedExec.
Syntax:
TimedExec [SILENT|REGULAR|VERBOUS][SKIP_MEM_CHECK] secondsToWait exeToStart [any args to pass to the exe]
Example 1 - Start executable with limited runtime of 10 sec:
TimedExec 10 MyTestExecutable.exe
Example 2 - Postbuildstep starts test executable:
rem Check if automatic test shall be skipped in this environment if "%NoTestAfterBuild%"== "" goto EXEC_TEST if %NoTestAfterBuild%==1 goto SKIP_TEST goto EXEC_TEST :SKIP_TEST echo Test after build is skipped (switched off by env var "NoTestAfterBuild") goto :eof :EXEC_TEST echo Executing unit test with time limitations rem next line has to be the last line to properly return rem the test execution code to the build sequence "$(TargetDir)\TimedExec.exe" 12 "$(TargetPath)"
When used within automatic testing TimedExec makes possible to proceed after failures within test executables that would usually block the test sequence or building process:
- assert boxes or system failure boxes after execution of invalid instructions
- endless loops
- deadlocks
Example of a test run with a endless looping demo executable within the postbuild step:
last line of script:
... "$(TargetDir)\TimedExec.exe" 12 "$(TargetPath)" ENDLESS_LOOP 0
Output to Stdout:
... Postbuildereignis wird ausgeführt... Executing unit test with time limitations [TimedExec]: Successfully started c:\\My Target\debug\DemoApp.exe "ENDLESS_LOOP" "0" [TimedExec]: Waiting 12 sec for program termination... [DemoApp] ----- Args Begin ----- [DemoApp] Commandline : "c:\My Target\debug\DemoApp.exe" "ENDLESS_LOOP" "0" [DemoApp] argc = 3 [DemoApp] arg 0: >c:\\My Target\\debug\\DemoApp.exe< [DemoApp] arg 1: >ENDLESS_LOOP< [DemoApp] arg 2: >0< [DemoApp] ----- Args End ----- [DemoApp]: starting endless loop... [TimedExec]: ERROR: Timeout of 12 sec elapsed before program has terminated! [TimedExec]: Killed c:\\My Target\\debug\\DemoApp.exe [TimedExec]: 07.10.2007 09:10:38 FAILURE (TIMEOUT_EXE_TERMINATION) DemoApp.exe StartTime: 07.10.2007 09:10:26 Timeout of 12 sec elapsed CommandLine: "c:\My Target\debug\\TimedExec.exe" 12 "c:\My Target\debug\DemoApp.exe" ENDLESS_LOOP EXIT_CODE 0 Project : error PRJ0019: Ein Tool hat einen Fehlercode aus folgender Quelle zurückgegeben: "Postbuildereignis wird ausgeführt..." ...
Changing behaviour:
Optional control via environment variables:
(Change behaviour without touching any source or script file)
TimedExec_Trace=SILENT|REGULAR|VERBOUS TimedExec_MinWaitTime=numberOfSeconds TimedExec_MaxWaitTime=numberOfSeconds (0 means infinite waiting) TimedExec_RestrictToSingleInstance=YES|NO (default is YES) TimedExec_MaxWaitTimeBeforeStartSec=numberOfSeconds (default 600 seconds, 0 means infinite waiting) TimedExec_LogResults=YES|NO (default is YES) TimedExec_LogFilePath=directoryPath (default is path of TimedExec.exe) TimedExec_SkipExecution=YES|NO (default is NO)
Basic settings:
The trace level set via environment variable "TimedExec_Trace" overrides the corresponding first optional command line param.
The wait time T specified within command line can be changed by defining environment variables "TimedExec_MinWaitTime" and "TimedExec_MaxWaitTime".
Rules for changing timeout value: if ((TimedExec_MinWaitTime exists) && (T < TimedExec_MinWaitTime)) T = TimedExec_MinWaitTime; if ((TimedExec_MaxWaitTime exists) && (T > TimedExec_MaxWaitTime)) T = TimedExec_MaxWaitTime;
Single execution instance:
It is possible to allow only the execution of a single TimedExec instance on a computer. If this feature is active and the program detects an already running instance it will wait until the other instance terminates and then proceed with starting the executable given within command line. If the other instance does not terminate (i.e. a configurable wait timeout elapses) TimedExec stops execution and returns an error code, i.e. the executable given in command line will not be started.
Environment variable "TimedExec_RestrictToSingleInstance" allows activation and deactivation of the feature. The maximum time to wait for termination of other execution instances can be changed with variable "TimedExec_MaxWaitTimeBeforeStartSec".
Possible usage in reality: Modern processors use parallel compiling of several projects/makefiles within a bigger project/makefile. Within the Postbuild steps the unit tests may be executed. If several unit tests need the same resource they can be synchronized simply by calling them via TimedExec. There is no need to implement synchronization features within the test code itself.
Logging of results:
Environment variable "TimedExec_LogResults" allows activation and deactivation of a final result message written to stdout. This message contains informations about execution time, executable to start and possible problems, which have occured.
If running with restriction to a single instance (see "TimedExec_RestrictToSingleInstance" above) the message is also written to a central logfile "TimedExec_Log.txt" within the directory where TimedExec.exe is stored. Each log entry is appended at the end of the file. Old entries remain unchanged until they are deleted by the user.
Remark: Accessing the file is only secure if it is guaranteed that only one executable performs the file access. This is true when running with restriction to a single instance.
Optionally the logfile directory can be changed via environment variable "TimedExec_LogFilePath".
Possible usage in real world: Results from multiple executions can be collected at a single place. In the context of testing the generated logfile may serve as a simple test protocol for a whole test suite.
Detection of memory leaks:
By default TimedExec will catch all output which the started executable writes to stdout and stderr to check for memory leak messages. In case of a detected memory leak an exit code of 1 is returned to signal the erraneous behaviour of the started executable. When the started executable has terminated all catched output will be written to stdout. (It is assumed that test applications have activated C runtime library detection of memory leaks. Then leaks will be reported by the message "Detected memory leaks" after program shutdown.)
With optional command line param SKIP_MEM_CHECK this behaviour can be switched off and the output of the started executable will not be affected.
Suppress execution:
Setting environment variable "TimedExec_SkipExecution" to YES allows to suppress the execution. In this case TimedExec will return an exit code of 0 after having checked the environment variables. The executable from commandline will not be started.
Possible usage in real world: If TimedExec is used within a bigger execution sequence (e.g. build script, batchfile, makefile, ...) it can simply be switched off without touching the scripts itself. Each user can setup his personal preferences. A development computer may be configured to not execute unit tests on each compilation, because tests will be started manually by the developer.
- See also:
- TimedExec.cpp
