creates and initializes a StopWatch
subroutine create_watch (watch, clock, name, err)
Creates and initializes the specified clocks of the specified watches. Upon return from create_watch , all clocks are not running and have the value 0. All watches must be created before they are used or added to a watch group. In Fortran 90 it is impossible to test whether or not a watch has been created, and using a watch that has not been created may cause the program to crash. It is not an error to create a watch that has already been created, however the prior information and memory locations will be lost. Watches should be destroyed (see destroy_watch(3)) before they are recreated. Also, local variable watches should be destroyed before returning from a subroutine, to avoid memory leaks.
One or more watches must be specified. The argument watch can be a single variable of type watchtype (see stopwatch(3)) to create one watch, or an array of type watchtype to create several watches.
The optional argument clock specifies which clocks to create on the specified watch(es). If omitted, the current default clocks (see option_stopwatch(3)) are created. If present, clock must be a character string containing 'cpu', 'user', 'sys', or 'wall', or an array of such character strings.
The optional argument name allows you to attach a name to the watch. The name is used when printing error messages, or when printing clock values using print_watch. If omitted, the name of the watch is 'unnamed watch'. If present, it must be of the same rank and dimension as watch. Watch names are limited to 132 characters.
If present, the optional intent OUT integer argument err returns a status code. The code is the sum of the values listed below.
An error message will be printed to a specified I/O unit (unit 6 by default) if print_errors is TRUE (default is TRUE). The error message contains more detail about the cause of the error than can be obtained from just the status code, so you should set print_errors to TRUE if you have trouble determining the cause of the error.
If abort_errors is TRUE (default is FALSE), the program will terminate on an error condition. Otherwise, the program will continue execution but the watch(es) will not be created.
See option_stopwatch(3) for further information on print_errors, abort_errors and I/O units.
The relevant status codes and messages are:
In addition to the run time diagnostics generated by StopWatch
, the following
problems may arise:
type (watchtype) w1, w2(3), w3
call create_watch(w2, name=(/'part 1', 'part 2', 'total '/), err=errcode)
call create_watch(w3, (/'cpu ', 'wall'/), err=errcode)
The first call creates the default clocks on a single watch with name 'unnamed watch'. The second call creates the default clocks on three watches given as an array and with names 'part 1', 'part 2', and 'total', and returns a status code. The third call creates one watch with the cpu and wall clocks, the name 'unnamed watch', and returns a status code.