Documentation for HiRes Time v1.2

The HiRes time library is meant to enable precise benchmarking of software written in Euphoria. This is done defining code fragments, or subsections, bracketed by calls to HRT_start() and HRT_stop() procedures. Subsections can be freely combined into sections. The results for a single section, or for all sections, can be sent to any file or device, with some control over formatting of the text output.

If you try to load the library under OSes which are not Windows, hardware that does not support high resolution timers (i486 or older) or older Windows versions (Win95 and WinNT3.1 support the API), a warning will be issued. The library will then operate using the standard time() function. The benefits of code (sub)sections are kept, but the results are less precise. You can usually compensate for this by performing more runs.

• HRT_all_results(object destination,object mode)    Sends output for all sections to the default file
• HRT_attach(integer section,object file,sequence mode)    Associates a file to a section
• HRT_auto(integer section,integer threshhold)    Sets auto reset threshhold for (all) sections.
• HRT_close(sequence filename)    Closes a file the library knows by its name
• HRT_disable(integer flags)    Frees memory and causes all routines to return immediately
• HRT_file(squence flags)    Returns the handle of a file known by name
• HRT_format(sequence file_name)    Sets format string for result output
• HRT_ordering(sequence items)    Sets order of values in output string
• HRT_reset(integer section, object flag)    Resets data for a section
• HRT_result(integer section_number,object destination,object mode)    Outputs results for a section
• HRT_results(object destination,object mode)    Outputs results for all sections, using section specific files if defined
• HRT_safe(integer safe_stop)    Determines whether to check if a stopped section was started.
• HRT_sections(integer number_of_sections)    Sets the number of sections to monitor
• HRT_start(integer section_number)    Start time watch for a section
• HRT_stop(integer section_number)    Stop time watch for a section and record data
• HRT_time()    Returns a time value, precise up to 10^-6s

• HRT_sections(integer number_of_sections)
• HRT_start(integer section_number)
• HRT_stop(integer section_number)
• HRT_safe(integer safe_stop)
• HRT_time()
• HRT_reset()
• HRT_auto()

procedure HRT_sections(integer number_of_sections)

Make this call to define how many sections will be monitored. If you don't, a default of 6 sections will be defined.
Using a value of 0 or less will disable he library. Results of currently monitored sections will be output if number_of_sections is less than 0.

procedure HRT_start(integer section_number)

Start monitoring time from the current statement on, and mark the timings as belonging to section numbered section_number. Valid numbers run from 1 to the maximum allowed value, either the default one or set by a call to HRT_sections().

procedure HRT_stop(integer section_number)

Stop monitoring the current code fragment, and accrue the timings to section numbered section_number.

procedure HRT_safe(integer safe_stop)

By default, when HRT_stop(some_section) is called, the library checks whether some_section is active. Since there is a little overhead incurred, you can disable the safety net and bypass the check by passing 0 to the procedure. All sections are affected. You can restore the default behaviour by passing a non zero value.
In safe mode, if you stop a section before starting it, the call is ignored. In non safe mode, you'll get weird timings.

function HRT_time()

Returns a time value which is precise up to the microsecond (in theory, to the tenth of a microsecond). If the library is not using the high resolution performance counters, this defaults to time().

function HRT_reset(integer section,object flag)

Resets total time and number of runs for section section to 0. If flag is 0, no further action is taken. If it is a nonzero atom, a message is output to the file recording the output of the section. The default message is "\nSection %d was reset after %d runs.\n". If it is a sequence, it is a new message for the procedure to output. It is recommended that the messge has a leading and trailing \n,. The first "%d" substring inside will be rendered as the section number, and the second one, if any, by the number of runs before reset. Don't include more than 2 format specifiers in the string. Use "" to revert to the default message.

procedure HRT_auto(integer section, integer threshholf)

Sets the threshhold, in number of runs, for auto reset of section section to threshhold. If section is 0, then all sections are affected. If threshhold is 0 or less, then auto reset is disabled.

Remarks:

• Subsections may freely overlap, and sections are made of as many subsections as needed. You can even start or stop a subsection assigning it to a section with a variable number. Calls to HRT_start() and HRT_stop() need not be nested.
• Since time monitoring starts or stops on an explicit HRT_start() or HRT_stop() call, you have to be careful to add such commands wherever they are needed - multiple if statements are places to watch out for.

The following procedures output section timings and control where it is done.

• HRT_result(integer section_number,object destination,object mode)
• HRT_results(object destination,object mode)
• HRT_all_results(object destination,object mode)

procedure HRT_result(integer section_number,object destination,object mode)

Outputs timings for the section section_number to the file or device designated by destination. If this is a number greater than 0, it is a file number. If it is 0, it is the last such handle defined for this section. If it is a sequence, the corresponding file will be opened using the mode option. In other cases, mode is ignored and may be passed as anything.

procedure HRT_results(object destination,object mode)

Proceeds as above for all defined sections. The output file is either the one specified in the arguments, or the particular file defined earlier for a particular section if different.

procedure HRT_all_results(object destination,object mode)

Proceeds as above for all defined sections. The output file is always the one specified in the arguments.

Remarks:

• You are responsible for closing all file handles thus created. Use HRT_close() to do so.
• If an output file is not defined, the standard output will be used.

Each section remembers whether its results were output using HRT_result(), and what was the file handle being used. HRT_results() and HRT_all_results() do not set these properties. Instead, they set a default file, to which HRT_all_results() outputs always, and HRT_results() selectively does. HRT_results() will use the default file for sections without a file attached to them, and that file if it exists.
For this reason, if you close a file passed to HRT_result(), you should open another one for the same section before the next call to HRT_results(). You may use HRT_attach() for this purpose.
If an invalid file is passed to HRT_all_results() or HRT_results(), the default file is defaulted to standard input. If an invalid file is passed to HRT_result(), the association for the involved section is undone.

The following procedures control how output is done.

• HRT_format(sequence format_string)
• HRT_ordering(sequence order)

procedure HRT_format(sequence format_string)

Changes the formatting string used to output results. The same string is being used irrespective of the output file, and used by printf() as a format string.
The default string is: "Section %d: Total elapsed time is %gs for %d runs;\n\t\t average execution time is %gs.\n".
If you change the number or order of arguments, you'll need to call the HRT_ordering() procedure below accordingly.
Since several results may be output to the same file, it is recommended that any new format string end with one or more end of line \n markers.
Use "" to revert to default formatting; in that case, calling HRT_ordering() is not required.

procedure HRT_ordering(sequence order)

Specifies what the format specifiers in the format string represent. The order sequence should have as many elements as there are format specifiers, and its elements should be taken from the following list:

• HRT_SECTION : the number of the section for which output is made
• HRT_TIME : total time for the runs reorded
• HRT_RUNS : number of runs recorded
• HRT_AVERAGE : the ratio total time/total runs

Note that, if no runs are recorded for a section, its average execution time is reported as 0s.0.

• HRT_close(sequence filename)
• HRT_file(sequence filename)
• HRT_attach(integer section,object file, sequence mode)

procedure HRT_close(sequence filename)

Closes the file specified by filename, which must have been opened earlier using HRT_result() or a related procedure. Be careful that a given filename may be associated to several sections.

procedure HRT_file(sequence file_name)

Returns the file handle associated with file_name if that file was opened by the library, and was not previously closed. Returns -1 if no such file can be found.

procedure HRT_attach(integer section,object file, sequence mode)

Associates a new file to the section section, without closing the former one assocuated, if any, nor outputting anything. file will be opened using mode. If file is invalid, the previous association will be undone.

The following routines are also provided by the library.

• HRT_disable(integer flags)

procedure HRT_disable(integer flags)

This is equivalent to calling HRT_sections(flags<0).
All memory will be released. You can enable the library later by calling HRT_sections() with a number of sections greater than zero.

For any comments, bug reports or requests, please email the author, currently Christian Cuvier .

The author(s) hereby decline any responsibility, direct, indirect or implied, for any adverse consequence of using the software this file documents.

Permission is granted to use, copy, modify and redistribute the software, with the following limitations:

• The documentation must come bundled with the library.
• These licensing terms shall never be modified.
• Any modification must clearly appear as such, and its author(s) be clearly marked as such.
• The author(s) of the software and documentation must be given adequate credit.

• November 2004: v1.0 released. It was only providing HRT_start, HRT_stop, HRT_time and HRT_results, the latter being equivalent to v1.1 HRT_all_results.
• June 2007: v1.1 adds many output control routines and configurable number of sections.
• August 2007: v1.2 adds auto reset configuration for sections, as well as a toggle to avoid some overhead when stopping a section.