A watch is a variable declared to be of type watchtype. It can be passed to subroutines as an actual argument or through modules like any Fortran variable, but can only be operated on by the StopWatch subroutines. Watches must be created by subroutine create_watch before they are used. Attempting to use a watch that has not been created will generate a Fortran 90 error, because this amounts to passing a pointer with undefined association status to the Fortran intrinsic function associated. Watches must be destroyed when no longer useful. For example, consider a local variable of type watchtype in a subroutine. Since the contents of a local variable are lost when the subroutine returns, the watch should be destroyed before returning to the calling program. Failure to destroy watches can lead to a memory leak.
Watches can optionally be given a name (up to 132 characters) through an optional argument, name, in create_watch. This name is used in error messages and print_watch to identify the watch in the printed output.
Different applications demand different definitions of ``time''. StopWatch supports four clocks in each watch, with each clock measuring a different concept of time. All of them measure time in seconds.
It is not required that all clocks be used. A watch can be created with any combination of the four clocks. You can also specify a set of default clocks to be used whenever the clocks are not explicitly determined.
Since Fortran 90 does not contain an intrinsic function for CPU time, the implementation of the cpu, sys and user clocks is system dependent. Some implementations may support only cpu and wall, not user and sys. Some implementations may support only wall. Since the Fortran 90 standard requires the existence of a system_clock subroutine, but does not require that it provide clock information, it is possible that some implementations might not support wall. Clock availability can be determined by inquiry_stopwatch (see Section 4.4). Unavailable clocks will automatically be removed from the set of default clocks, but if a clock that is not available is explicitly requested, a warning message will be generated.
StopWatch supports multiple watches simultaneously. Often it is useful to perform the same operation on several watches. This is essential for correct operation of pause_watch and end_pause_watch and is convenient for procedures like read_watch, print_watch and reset_watch. To facilitate this, StopWatch supports the concept of watch groups. When calling a StopWatch subroutine, a watch group can be specified instead of a watch. The group is referenced by a variable of type watchgroup. Watch groups must be created before they are used. Attempting to use a watch group that has not been created will generate a Fortran 90 error, because this amounts to passing a pointer with undefined association status to the Fortran intrinsic function associated. Watch groups must be destroyed when no longer useful. The watches themselves are not destroyed, only the grouping of them. Failure to destroy watch groups can lead to a memory leak.
Most StopWatch subroutines take watch as the first dummy argument, and accept several forms of watch. The forms are:
In most StopWatch routines, an array of watches can be specified by an array constructor in the calling statement, for example:
type (watchtype) watch :: w1, w2, w3 call print_watch( (/w1,w2,w3/) )
However, this can not be used in routines where watch has intent OUT or intent INOUT, because the array constructor is actually an expression, not a list of the variables. Currently this prohibits the use of array constructors in the arguments to the routines create_watch and destroy_watch.
Most StopWatch subroutines take clock as the (optional) second dummy argument to determine which of the four clocks will be affected by the action. clock can be one of the character strings 'user', 'sys', 'cpu', or 'wall', or can be an array of such character strings to specify more than one clock. Since clock is always intent IN, an array of clock types can be built with an array constructor. However, note that Fortran 90 requires all character strings in such a construction to have the same length. Thus 'sys' and 'cpu' should be padded with a blank, as in:
call start_watch(watch, (/'user','sys ','cpu '/) )
If the optional argument clock is omitted, the current set of default clocks is used. The set of default clocks is set with option_stopwatch (see Section 4.4) and initially consists of all available clocks.