– Typee Documentation –

5 – Typee Built-in Libraries

5.SysTime Library

Path Libs/SysTime/.

Contained modules are

  • systime.ty: deals with the System time, Cpu time and Process time;
  • perfmeter.ty: offers two performance measurement tools with high precision.

Module systime.ty

Defines functions that return System time, Cpu time and Process time. Returned values may slightly differ according to the targeted programming language.

target language available since Typee version
C++ 1.0
C# 1.0
Java & Android 1.0
Python 1.0
float32 systime()

Returns the System time in seconds, with milliseconds as precision. The system time is the elapsed time from epoch time, which is, whatever the targeted programming language and the platform, January 1st, 1970, 00:00.
Caution: this time may go backward when system clock value is modified. The system time should not be used to evaluate performances.

float64 systime_ns()

Returns the System time in seconds, with nanoseconds as precision. The system time is the elapsed time from epoch time, which is, whatever the targeted programming language and the platform, January 1st, 1970, 00:00.
Caution: this time may go backward when system clock value is modified. The system time should not be used to evaluate performances.
Notice: for nearly all platforms and systems, actual precision is 100 ns.

float32 cputime()

Returns the CPU time in seconds, with milliseconds as precision. Includes slept time. The start value for CPU time is undefined. cputime() can be used to evaluate performances since it ensures no backward timing.
Caution: with C#, cputime() is a wrapper to systime() – so, it may lead to backward timings with C#.

float64 cputime_ns()

Returns the CPU time in seconds, with nanoseconds as precision. Includes slept time. The start value for CPU time is undefined. cputime_ns() can be used to evaluate performances since it ensures no backward timing.
Caution: with C#, cputime_ns() is a wrapper to systime_ns() – so, it may lead to backward timings with C#.
Notice: for nearly all platforms and systems, actual precision is 100 ns.

float32 proctime()

Returns the Process time in seconds, with milliseconds as precision. Does not include slept time. The start value for CPU time is undefined. proctime() can be used to evaluate performances since it ensures no backward timing.
Caution: with C#, proctime() is a wrapper to systime() – so, it may lead to backward timings with C#.

float64 proctime_ns()

Returns the Process time in seconds, with nanoseconds as precision. Does not include slept time. The start value for CPU time is undefined. proctime_ns() can be used to evaluate performances since it ensures no backward timing.
Caution: with C#, proctime_ns() is a wrapper to systime_ns() – so, it may lead to backward timings with C#.
Notice: for nearly all platforms and systems, actual precision is 100 ns.

Module perfmeter.ty

Aims at measuring the process elapsed time between two timing points.

language available since Typee version
pure Typee 1.0

Defines two classes, PerfMeter and PerfMeterHms.

class PerfMeter

Elapsed times are printed on console with seconds as units and with the maximum precision according to the platform.

PerfMeter()

Default constructor.
Initiates the measuring of consumed time in process.

PerfMeter( const ? in (str,str16) format )

Constructor with time printing format.
Initiates the measuring of consumed time in process.
format is a string used for the formatting of the later printing of the consumed time in process.
Class PerfMeter internally defines a default format: "\n-- done in {:.6f} s". You can see in there that the formating strings may contain any kind of text plus a mandatory item specifier for a floating point number. This one defaults to 6 decimals for the fractional part of the elapsed seconds from start of processing time measurement. You can set it to anything else via argument format but it must contain one and only one item specifier of the form "{:<width>.<frac>f}" with:

  • width an optional number that represents the total width of the printed field (dot included);
  • frac an optional number that repesents the number of fractional digits printed after the dot.

or it may contain as many items specifiers of the same form as long as they contain 0 for the identification of the item to be formatted: "{0:<width>.<frac>f}".
When numbers width and frac are missing, the separating dot may be ommitted before specifier f.

none destroy()

Destructor.
Automatically called when instance is deleted. This is the case when getting out of the statements block of a with statement – see examples at end of this sub-section.

none mark()

Gets current processing time and internally remembers it. This will be later used, for instance when printing the consumed time since start of measurement.

none restart()

Restarts the time measurement. Sets the new starting point of measurement at now and clears the last marked time.

str operator str()
str16 operator str16()

Returns a string containing the formated elapsed process time between starting point of measurement and last marked time.
If no mark has been set, these operators automatically mark the current process time.
The returned string is formatted according to either the default formatting string or the formatting string passed at instantiation time.
Notice that these operators are implicitely called when printing an instance of PerfMeter

Examples of Use

from SysTime.perfmeter import PerfMeter;

print( 'start' );
with PerfMeter() as pm {
    for( uint64 i in [:0xffff_ffff) )
        float64 f = float64(i) * 1.23456789e15;
}

// prints:
// start
// -- done in 30.100176 s

Explanations:
The constructor PerfMeter() called in clause with instantiates the class. The reference of this unnamed instance is assigned to pm. When leaving the block of statements after with, the destructor of class PerfMeter is silently called on pm. This destructor automatically marks current time and prints the difference between this last mark and the starting time, according to the default format string.

Modifying the formating string:

from SysTime.perfmeter import PerfMeter;

print( 'start' );
with PerfMeter( "consumed time: {0:.3f} s -- {0:.7f} s") as pm {
    for( uint64 i in [:0xffff_ffff) )
        float64 f = float64(i) * 1.23456789e15;
}

// prints:
// start
// consumed time: 30.081 s -- 30.0807423 s

Printing marks during processing:

from SysTime.perfmeter import PerfMeter;

print( 'start' );
with PerfMeter( "{:.4f} s") as pm {
    for( uint64 i in [:0xffff_ffff) ) {
        float64 f = float64(i) * 1.23456789e15;
        if( i == 0x8000_0000 )
            print( pm );
}

// prints:
// start
// 15.4034
// 30.5242
class PerfMeterHms

Elapsed times are printed on console with format HH:MM:SS.frac and with the maximum precision according to the platform.

PerfMeterHms()
PerfMeterHms( const uint8 decimals )

Default constructor.
Initiates the measuring of consumed time in process.
When argument decimals is provided, this sets the number of digits to be used when printing the fractional part of seconds. Defaults to 6.

PerfMeterHms( const ? in (str,str16) format )
PerfMeterHms( const ? in (str,str16) format, const uint8 decimals )

Constructor with time printing format.
Initiates the measuring of consumed time in process.
When argument decimals is provided, this sets the number of digits to be used when printing the fractional part of seconds. Defaults to 3. Max number of printed fractional digits is 6.
format is a string used for the formatting of the later printing of the consumed time in process.
Class PerfMeterHms internally defines a default format: "\n-- done in {:s}". You can see in there that the formating strings may contain any kind of text plus a mandatory item specifier for the HH:MM:SS.frac number. It defaults to 3 decimals for the fractional part of the elapsed seconds from start of processing time measurement. You can set it to anything else via argument format but it must contain one and only one item specifier of the form "{:<width>s}" or "{}" with: width an optional number that represents the total width of the printed field (colons and dot included) or it may contain as many items specifiers of the same form as long as they contain 0 for the identification of the item to be formatted: "{0:<width>s}" or "{0}".

none destroy()

Destructor.
Automatically called when instance is deleted. This is the case when getting out of the statements block of a with statement – see examples at end of this sub-section.

none mark()

Gets current processing time and internally remembers it. This will be later used, for instance when printing the consumed time since start of measurement.

none restart()

Restarts the time measurement. Sets the new starting point of measurement at now and clears the last marked time.

str operator str()
str16 operator str16()

Returns a string containing the formated elapsed process time between starting point of measurement and last marked time.
If no mark has been set, these operators automatically mark the current process time.
The returned string is formatted according to either the default formatting string or the formatting string passed at instantiation time.
Notice that these operators are implicitely called when printing an instance of PerfMeterHms

Examples of Use

from SysTime.perfmeter import PerfMeterHms;

print( 'start' );
with PerfMeterHms() as pm {
    for( uint64 i in [:0xffff_ffff) )
        float64 f = float64(i) * 1.23456789e15;
}

// prints:
// start
// -- done in 0:30.100

Explanations:
The constructor PerfMeterHms() called in clause with instantiates the class. The reference of this unnamed instance is assigned to pm. When leaving the block of statements after with, the destructor of class PerfMeterHms is silently called on pm. This destructor automatically marks current time and prints the difference between this last mark and the starting time, according to the default format string.

Modifying the formating string:

from SysTime.perfmeter import PerfMeterHms;

print( 'start' );
with PerfMeterHms( "consumed time: {0} -- {0}", 6 ) as pm {
    for( uint64 i in [:0xffff_ffff) )
        float64 f = float64(i) * 1.23456789e15;
}

// prints:
// start
// consumed time: 0:30.080742 -- 0:30.080742

Printing marks during processing:

from SysTime.perfmeter import PerfMeterHms;

print( 'start' );
with PerfMeterHms( 4 ) as pm {
    for( uint64 i in [:0xffff_ffff) ) {
        float64 f = float64(i) * 1.23456789e15;
        if( i == 0x8000_0000 )
            print( pm );
}

// prints:
// start
// 0:15.4034
// 0:30.5242

 
Next section explains built-in library Thread.

< previous (5. built-in lib Strings) | (5. built-in lib Thread) next >