creates a StopWatch
subroutine create_watchgroup (watch, handle, err)
Creates a new watch group and returns a handle for it. A watch group must be created by this routine before it is passed to any other StopWatch routines. In Fortran 90 it is impossible to test whether or not a watch group has been created, and using a watch group that has not been created may cause the program to crash. It is not an error to create a watch group that has already been created, however the prior information and memory locations will be lost. Watch groups should be destroyed (see destroy_watchgroup(3)) before they are recreated. Also, local variable watch groups should be destroyed before returning from a subroutine, to avoid memory leaks.
One or more watches may be optionally specified. If watch is present, the watch group will initially contain the specified watch(es). If watch is omitted, the watch group will initially be empty. Watches can be added and removed from the group with join_watchgroup and leave_watchgroup.
The argument watch can be a single variable of type watchtype (see stopwatch(3)) to start the group with one watch, or an array of type watchtype to start the group with several watches.
The argument handle is a variable of type watchgroup that will subsequently be used to access the watch group.
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 group 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:
type (watchtype) w(3)
type (watchgroup) g1, g2
call create_watchgroup(w, g2, err=errcode)
The first call creates an empty group g1. The second call creates the group g2 with three watches, and returns a status code.
It cannot be determined whether or not a watch variable has been created (passed as an argument to create_watch). If a watch that has never been created is passed into create_watchgroup, it might generate a Fortran error due to passing a pointer with undefined association status to the Fortran intrinsic function associated. Some compilers will allow this as an extension to the Fortran 90 standard and recognize that the pointer is not associated, in which case the ``Watch needs to be created'' error message is generated.