create_watchgroup

CREATE_WATCHGROUP

creates a StopWatch watch group

SYNOPSIS
subroutine create_watchgroup (watch, handle, err)

type (watchtype), intent(IN) :: watch

OR

type (watchtype), intent(IN) :: watch(:)

type (watchgroup), intent(OUT) :: handle

integer, optional, intent(OUT) :: err

DESCRIPTION
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.

DIAGNOSTICS
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:

0

No errors; execution successful.

1

Watch needs to be created. This error occurs if you attempt to put a watch that has been destroyed in the group. The watch must first be created again. See also the comment about watches that have never been created in the BUGS section.

512

Failed to allocate required memory. When a group is created, memory is allocated for the group. Also, when create_watchgroup is called with an array of watches, temporary memory is allocated. This error occurs if the Fortran allocate statement returns a nonzero status indicating that memory could not be allocated. Avoid memory leaks by always destroying watches and groups before recreating them, and destroying local variable watches and groups before returning from a subroutine.

1024

Error occurred while deallocating memory. This error occurs if the Fortran deallocate statement returns a nonzero status while deallocating temporary memory used for an array of watches. The group is created, but be aware that other problems could develop as a result of the deallocate error.

EXAMPLES
type (watchtype) w(3)
type (watchgroup) g1, g2
integer errcode

call create_watchgroup(handle=g1)
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.

BUGS
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.