Timer

#include <Timer.h>

S	Return	Name	Parameters
		Timer	(void)

	void	Start	(void)
	uint64	Reset	(void)
	uint64	Restart	(void)
	uint64	GetElapsed	(void) const
	bool	HasStarted	(void) const
	bool	HasExpired	(uint64 time) const
✔	void	Sleep	(const Range& time)
✔	void	Sleep	(uint32 minimum, uint32 maximum)
✔	uint64	GetCpuTime	(void)

	uint64	operator ()	(void) const
	bool	operator <	(const Timer& timer) const
	bool	operator >	(const Timer& timer) const
	bool	operator <=	(const Timer& timer) const
	bool	operator >=	(const Timer& timer) const
	bool	operator ==	(const Timer& timer) const
	bool	operator !=	(const Timer& timer) const

Description

Represents a monotonic timer used for calculating elapsed times with millisecond accuracy. Elapsed times are useful for determining the amount of time passed between two events, such as in the case of performance tuning and time-sensitive operations. Since the timer is monotonic, it does not overflow and it operates completely independent of the system clock. This has the added benefit of being immune to time adjustments and changes to the time zone settings.

Unfortunately, there is no way to convert elapsed times to human-readable formats, meaning that elapsed times can only be compared with other elapsed times that use the same reference. Elapsed times also shouldn't be exchanged across a network or saved to disk, since there is no way of telling whether the computer receiving this data will be compatible or has even been rebooted. It is, however, possible to exchange elapsed times with other processes running on the same machine, provided they also use the same reference clock.

Use the Start function to take a snapshot of the current clock. This snapshot will be used as the starting reference when computing elapsed times. Use the Reset function to return the current elapsed time and reset the class back to its initial state. Calling Restart will return the current elapsed time and restart the timer. Use the GetElapsed function to get the current elapsed time. Helper functions like HasStarted can be used to determine whether the class has been started and HasExpired can be used to determine if the class has expired by a specified number of milliseconds.

The Timer class can also be used to block the execution of the current thread for a specified amount of time through the Sleep function. Furthermore, the current platform-dependent clock value can also be retrieved through the GetCpuTime function. This level of direct access enables everybody to create functionality similar to what is provided by the class. Relational operators and comparison is supported as well.

Constructors

    
        


            Timer
            (void)

Constructs an unstarted timer which can be started with the Start function.

Functions

    
        

            void
            Start
            (void)

Starts this timer by taking a snapshot of the current clock. Once started, elapsed times can be retrieved through the GetElapsed function. Normally, a timer is started just before a lengthy operation, as illustrated in the example below:

// Create and start a timer
Timer timer; timer.Start();

// Some slow operation here

// Get elapsed time
timer.GetElapsed();

    
        

            uint64
            Reset
            (void)

Resets this class back to its initial state and returns the elapsed time since the previous call to Start. If this timer was not previously started, this function will return zero.

    
        

            uint64
            Restart
            (void)

Restarts the timer and returns the elapsed time since the previous call to Start. If this timer was not previously started, this function will return zero. This function is equivalent to obtaining the elapsed time and starting the timer again, but it does so in a single operation, avoiding the need to obtain the clock value twice.

    
        

            uint64
            GetElapsed
            (void) const

Returns the number of milliseconds since this timer was started. If this timer has not yet been started, this function will return zero.

    
        

            bool
            HasStarted
            (void) const

Returns true if this timer has been started.

    
        

            bool
            HasExpired
            (uint64 time) const

Returns true if this timer's elapsed time is greater than time milliseconds, or if this timer has not yet been started.

    
        
            static
            void
            Sleep
            (const Range& time)
        
        
            static
            void
            Sleep
            (uint32 minimum,
 uint32 maximum)

Blocks the execution of the current thread for time milliseconds. If time is a range between two numbers, a pseudorandom number between that range will be used instead. This function does nothing if time is negative.

    
        
            static
            uint64
            GetCpuTime
            (void)

Returns the current platform-dependent clock value, in milliseconds. On Linux, this function will return the result of clock_gettime with the CLOCK_MONOTONIC identifier. On Mac, this function will return the result of mach_absolute_time. On Windows, this function will return the result of QueryPerformanceCounter, or GetTickCount64 if for some reason QueryPerformanceFrequency fails to initialize.

Operators

    
        

            uint64
            operator ()
            (void) const

This function is identical to GetElapsed, as illustrated in the example below:

// Create and start a timer
Timer timer; timer.Start();

// Two ways of obtaining time
timer.GetElapsed() == timer();

    
        

            bool
            operator <
            (const Timer& timer) const
        
        

            bool
            operator >
            (const Timer& timer) const
        
        

            bool
            operator <=
            (const Timer& timer) const
        
        

            bool
            operator >=
            (const Timer& timer) const

Performs relational comparison using the elapsed time of this timer and timer. If either timer has not yet been started, this function will return true or false depending on which makes the most sense. This function is equivalent to retrieving the elapsed times of both timers and performing the relational operation between them, as illustrated in the example below:

// Create and start timers
Timer timer1; timer1.Start();
Timer timer2; timer2.Start();

// Example of equivalent relational operations
(timer1 <  timer2) == (timer1() <  timer2());
(timer1 >  timer2) == (timer1() >  timer2());
(timer1 <= timer2) == (timer1() <= timer2());
(timer1 >= timer2) == (timer1() >= timer2());

    
        

            bool
            operator ==
            (const Timer& timer) const
        
        

            bool
            operator !=
            (const Timer& timer) const

Performs equality comparison to determine whether two timers were started at the same time.

Examples

// C++
#include <Robot.h>
ROBOT_NS_USE_ALL;

int main (void)
{
    // Create and start a timer
    Timer timer; timer.Start();

    timer.HasStarted (  ); // True
    timer.HasExpired (50); // False

    // Some slow operation here
    Timer::Sleep (1000, 2000);

    timer.HasStarted (  ); // True
    timer.HasExpired (50); // True

    // Get elapsed time in milliseconds
    // since calling the Start function
    timer.GetElapsed(); /* or */ timer();

    // Create copy and restart the timer
    Timer copy = timer; timer.Restart();

    // Copy started first so timer < copy
    timer < copy; // == timer() < copy()
    timer > copy; // == timer() > copy()

    timer.Reset(); // timer.GetElapsed()
    copy .Reset(); // copy .GetElapsed()

    timer == copy; // True
    timer != copy; // False

    // Platform dependent
    Timer::GetCpuTime();
    return 0;
}

// Node
var robot = require ("robot-js");

// Create and start timer
var timer = robot.Timer();
timer.start();

timer.hasStarted (  ); // True
timer.hasExpired (50); // False

// Some slow operation in here
robot.Timer.sleep (1000, 2000);

timer.hasStarted (  ); // True
timer.hasExpired (50); // True

// Get elapsed time in milliseconds
// since calling the Start function
timer.getElapsed();

// Create a new copy and restart the timer
var copy = timer.clone(); timer.restart();

// Copy started first so timer < copy
timer.lt (copy); // True
timer.gt (copy); // False

timer.reset(); // timer.getElapsed()
copy .reset(); // copy .getElapsed()

timer.eq (copy); // True
timer.ne (copy); // False

// Platform dependent
robot.Timer.getCpuTime();

static	void	Sleep	(const Range& time)
static	void	Sleep	(uint32 minimum, uint32 maximum)