NAME

ACE_High_Res_Timer - A high resolution timer class wrapper that encapsulates OS-specific high-resolution timers, such as those found on Solaris, AIX, Win32/Pentium, and VxWorks.

SYNOPSIS

#include <ace/High_Res_Timer.h>

class ACE_High_Res_Timer { public: static void global_scale_factor (ACE_UINT32 gsf); static ACE_UINT32 global_scale_factor (); static int get_env_global_scale_factor ( const char *env = "ACE_SCALE_FACTOR" ); ACE_High_Res_Timer (void); void reset (void); void start ( const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME ); void stop ( const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME ); void elapsed_time (ACE_Time_Value &tv); void elapsed_time (ACE_hrtime_t &nanoseconds); void elapsed_time (struct timespec &); void elapsed_microseconds (ACE_hrtime_t &usecs) const; void start_incr ( const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME ); void stop_incr ( const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME ); void elapsed_time_incr (ACE_Time_Value &tv); void print_total ( const char *message, const int iterations = 1, ACE_HANDLE handle = ACE_STDOUT ); void print_ave ( const char *message, const int iterations = 1, ACE_HANDLE handle = ACE_STDOUT ); void dump (void) const; ACE_ALLOC_HOOK_DECLARE; ACE_OS::ACE_HRTIMER_GETTIME); protected: static u_long get_registry_scale_factor (void); private: static void hrtime_to_tv ( ACE_Time_Value &tv, const ACE_hrtime_t hrt ); ACE_OS::ACE_HRTIMER_GETTIME); ACE_hrtime_t start_; ACE_hrtime_t end_; ACE_hrtime_t total_; ACE_hrtime_t start_incr_; static ACE_UINT32 global_scale_factor_; };

DESCRIPTION

Most of the member functions don't return values. The only reason that one would fail is if high-resolution time isn't supported on the platform. To avoid impacting performance and complicating the interface, in that case, ACE_OS::gettimeofday () is used instead.

The global scale factor is required for platforms that have high-resolution timers that return units other than microseconds, such as clock ticks. It is represented as a static u_long, can only be accessed through static methods, and is used by all instances of High Res Timer. The member functions that return or print times use the global scale factor. They divide the "time" that they get from ACE_OS::gethrtime () by global_scale_factor_ to obtain the time in microseconds. Its units are therefore 1/microsecond. On Solaris, a scale factor of 1000 should be used because its high-resolution timer returns nanoseconds. However, on Intel platforms, we use RDTSC which returns the number of clock ticks since system boot. For a 200MHz cpu, each clock tick is 1/200 of a microsecond; the global_scale_factor_ should therefore be 200.

NOTE: the elapsed time calculations in the print methods use ACE_hrtime_t values. Those methods do _not_ check for overflow!

NOTE: Gabe begeddov@proaxis.com raises this issue regarding ACE_OS::gethrtime (): on multi-processors, the processor that you query for your timer.stop () value might not be the one you queried for timer.start (). Its not clear how much divergence there would be, if any.

This issue is not mentioned in the Solaris 2.5.1 gethrtime man page.

Initialization method.

static void global_scale_factor (ACE_UINT32 gsf);

static ACE_UINT32 global_scale_factor ();

static int get_env_global_scale_factor (
    const char *env = "ACE_SCALE_FACTOR"
    );

ACE_High_Res_Timer (void);

void reset (void);

void start (
    const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME
    );

void stop (
    const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME
    );

void elapsed_time (ACE_Time_Value &tv);

void elapsed_time (ACE_hrtime_t &nanoseconds);

void elapsed_time (struct timespec &);

void elapsed_microseconds (ACE_hrtime_t &usecs) const;

void start_incr (
    const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME
    );

void stop_incr (
    const ACE_OS::ACE_HRTimer_Op = ACE_OS::ACE_HRTIMER_GETTIME
    );

void elapsed_time_incr (ACE_Time_Value &tv);

@@ These two functions are currently not supported on Windows CE. However, we should probably use the handle and ACE_Log_Msg to print out the result.

void print_total (
    const char *message,
    const int iterations = 1,
    ACE_HANDLE handle = ACE_STDOUT
    );

void print_ave (
    const char *message,
    const int iterations = 1,
    ACE_HANDLE handle = ACE_STDOUT
    );

void dump (void) const;

ACE_ALLOC_HOOK_DECLARE;

ACE_OS::ACE_HRTIMER_GETTIME);

AUTHOR

Doug Schmidt

LIBRARY

ace