Manual Reference Pages  - CREATE_WATCH (3)

NAME

create_watch(3f) - [M_stopwatch] creates and initializes a M_StopWatch watch (LICENSE:PD)

CONTENTS

Synopsis
Description
Diagnostics
Examples
Bugs
Author
See Also

SYNOPSIS

subroutine create_watch(watch, clock, name, err)

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

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

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

integer, optional, intent(OUT) :: err

DESCRIPTION

Creates and initializes the specified clocks of the specified watches. In the initial state, all clocks are not running and have the value 0. All watches must be created before they are used or added to a watch group. In Fortran 90 it is impossible to test whether or not a watch has been created, and using a watch that has not been created may cause the program to crash. It is not an error to create a watch that has already been created, however the prior information and memory locations will be lost. Watches should be destroyed (see destroy_watch(3)) before they are recreated. Also, local variable watches should be destroyed before returning from a subroutine, to avoid memory leaks.

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

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

The optional argument name allows you to attach a name to the watch. The name is used when printing error messages, or when printing clock values using print_watch. If omitted, the name of the watch is ’unnamed watch’. If present, it must be of the same rank and dimension as watch. Watch names are limited to 132 characters.

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

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.

32 Number of names is not equal to number of watches. This occurs if the array of watch names, name, is not of the same length as the array of watches, watch.

64 Character string too long. This occurs when a watch name has more than 132 characters. The watch is created, but the name is truncated to the first 132 characters.

512 Failed to allocate required memory. Creating a watch involves allocating memory for it. Also, when create_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 created, but be aware that other problems could develop as a result of the deallocate error.

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

o Since watch has intent OUT, you cannot use an array constructor as an actual argument to construct an array of watches. Some compilers will recognize this as a compile time error, but will generate an obscure error message, such as ‘‘no specific match for generic name’’.

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 ’, and pad watch names so they all have the same length (within an array constructor).

EXAMPLES

type (watchtype) w1, w2(3), w3 integer errcode

call create_watch(w1) call create_watch(w2, name=(/’part 1’, ’part 2’, ’total '/), err=errcode) call create_watch(w3, (/’cpu ’, ’wall’/), err=errcode)

The first call creates the default clocks on a single watch with name ’unnamed watch’. The second call creates the default clocks on three watches given as an array and with names ’part 1’, ’part 2’, and ’total’, and returns a status code. The third call creates one watch with the cpu and wall clocks, the name ’unnamed watch’, and returns a status code.

program demo_creat_watch ! example program starts a watch W1, stops it, and prints the results use,intrinsic :: iso_fortran_env, only : & ERROR_UNIT, INPUT_UNIT, OUTPUT_UNIT ! access computing environment use M_stopwatch, only : watchtype use M_stopwatch, only : option_stopwatch, create_watch, start_watch use M_stopwatch, only : stop_watch, print_watch, destroy_watch implicit none type (watchtype) w1 character(len=:),allocatable :: cmd integer errcode

cmd=’hostname;sleep 3;date;pwd’

call option_stopwatch( & default_clock=[character(len=4) :: ’cpu’,’wall’,’user’,’sys’], & io_unit_print=ERROR_UNIT, & io_unit_error=ERROR_UNIT)

call create_watch(watch=w1, name=’times’) call start_watch(watch=w1)

call execute_command_line(cmd) ! do something that takes some time

call stop_watch(watch=w1) call print_watch(watch=w1, title=’COMMAND:’//cmd, err=errcode) call destroy_watch(w1)

end program demo_creat_watch

Expected typical output:

   buzz
   Sun Nov  4 20:56:29 EST 2018
   /home/urbanjs/V600
   COMMAND:hostname;sleep 3;date;pwd
     times:
           cpu=    0.03 user=    0.00  sys=    0.03 wall=    3.38

BUGS

None known.

AUTHOR

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

SEE ALSO

M_stopwatch(3), create_watchgroup(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), print_watch(3), read_watch(3), reset_watch(3), start_watch(3), stop_watch(3)


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