Manual Reference Pages  - LEAVE_WATCHGROUP (3)

NAME

leave_watchgroup(3f) - [M_stopwatch] removes a M_StopWatch watch from a watch group (LICENSE:PD)

CONTENTS

Synopsis
Description
Diagnostics
Examples
Bugs
Author
See Also

SYNOPSIS

subroutine leave_watchgroup(watch, handle, err)

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

type (watchgroup), intent(INOUT) :: handle
integer, optional, intent(OUT) :: err

DESCRIPTION

Removes the specified watch(es) from the specified watch group.

One or more watches must be specified. The argument watch can be a single variable of type watchtype (see M_stopwatch(3)) to remove one watch, or an array of type watchtype to remove several watches.

The watch group is specified by handle, a variable of type watchgroup.

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(es) will not be removed from the group.

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.

128 Watch not found in given group. This occurs when you attempt to remove a watch from a group that it does not belong to. One cause of this is if you destroy a watch and later try to remove it from a group.

512 Failed to allocate required memory. When leave_watchgroup is called with an array or group 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 or group of watches or the memory used for an entry in the group. The watches are removed from the group, but be aware that other problems could develop as a result of the deallocate error.

EXAMPLES

type (watchtype) w1, w2(3) type (watchgroup) g1 integer errcode

call leave_watchgroup(w1, g1) call leave_watchgroup(w2, g1, errcode)

The first call removes the watch w1 from watch group g1. The second call removes three watch from g1 and returns a status code.

BUGS

It cannot be determined whether or not a watch variable or watch group has been created (passed as an argument to create_watch or create_watchgroup). If a watch or watch group that has never been created is passed into leave_watchgroup, it might generate a Fortran error due to passing a pointer with undefined association status to the Fortran intrinsic function associated. However, 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.

AUTHOR

William F. Mitchell, william.mitchell@nist.gov National Institute of Standards and Technology

SEE ALSO

M_stopwatch(3), create_watchgroup(3), create_watch(3), destroy_watchgroup(3), destroy_watch(3), end_pause_watch(3), inquiry_stopwatch(3), join_watchgroup(3), option_stopwatch(3), pause_watch(3), print_watch(3), read_watch(3), reset_watch(3), start_watch(3), stop_watch(3)


M_StopWatch 1.1 LEAVE_WATCHGROUP (3) September 22, 2017
Generated by manServer 1.08 from leave_watchgroup.3m_stopwatch.txt using man macros.