Manual Reference Pages  - PRINT_WATCH (3)

NAME

print_watch(3f) - [M_stopwatch] prints the current value of a M_StopWatch watch (LICENSE:PD)

CONTENTS

Synopsis
Description
Diagnostics
Examples
Bugs
Author
See Also

SYNOPSIS

subroutine print_watch(watch, clock, title, form, err)

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

character(len=*), optional, intent(IN) :: clock
OR character(len=*), intent(IN) :: clock(:)

character(len=*), optional, intent(IN) :: title, form

integer, optional, intent(OUT) :: err

DESCRIPTION

Prints the specified clocks of the specified watches. A title line is printed followed by two lines for each watch, the first containing the name of the watch and the second containing the values of the specified clocks. Output is written to a user specified I/O unit (see option_stopwatch(3)) which is 6 by default.

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

The optional argument clock specifies which clocks to print from the specified watch(es). If omitted, the current default clocks (see option_stopwatch(3)) are printed. If present, clock must be a character string containing ’cpu’, ’user’, 'sys’, or ’wall’, or an array of such character strings.

The optional argument title is a character string to be printed before printing the watch values. If omitted, the string ‘‘Times printed by M_StopWatch:’’ is printed.

The optional argument form determines the form for printing time. The valid values are: .IP ’sec’, seconds
’hh:mm:ss’, colon separated hours, minutes and seconds
’[[hh:]mm:]ss’, same as ’hh:mm:ss’ except hours and minutes are printed only if nonzero If omitted, the current default form is used. The default form is initially ’sec’ and can be reset by option_stopwatch(3)

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

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 print a watch that has been destroyed. The watch must first be created again. See also the comment about watches that have never been created in the BUGS section.

4 Watch is in an unknown state. This occurs if M_StopWatch does not recognize the state (running, stopped, etc.) that the watch is in. This error should not occur, and indicates an internal bug in M_StopWatch.

8 Invalid clock type. This occurs if clock is present and one of the specified clocks is not supported by the implementation. See inquiry_stopwatch(3) to determine what clocks are available.

256 I/O unit is not open for writing. The I/O unit to which print_watch expects to write is not open for writing. The I/O unit number is set by io_unit_print in option_stopwatch and is 6 by default.

512 Failed to allocate required memory. When print_watch 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. The watches are printed, but be aware that other problems could develop as a result of the deallocate error.

2048 Illegal output form. This error occurs if form is not one of the strings listed above.

In addition to the run time diagnostics generated by M_StopWatch, the following problems may arise:

o In Fortran 90, the character strings in an array constructor must all have the same length. Pad three letter clock names with a blank on the right to make a four character string, for example, ’cpu ’.

EXAMPLES

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

call print_watch(w1) call print_watch(w2, title=’Array of 3 watches’, err=errcode) call print_watch(g1, (/’cpu ’, ’wall’/), errcode)

The first call prints the default clocks from a single watch, and the default title. The second call prints the default clocks on three watches given as an array and the title ‘‘Array of 3 watches’’, and returns a status code. The third call prints the cpu and wall clocks on the watches in the group 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 print_watch, 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), leave_watchgroup(3), option_stopwatch(3), pause_watch(3), read_watch(3), reset_watch(3), start_watch(3), stop_watch(3)


M_StopWatch 1.1 PRINT_WATCH (3) September 22, 2017
Generated by manServer 1.08 from print_watch.3.txt using man macros.