---
name: "ACE_High_Res_Timer"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_High_Res_Timer"
---

# ACE\_High\_Res\_Timer(3)

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

## 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 (void);
    static int get_env_global_scale_factor (
        const char *env = "ACE_SCALE_FACTOR"
        );
    static ACE_UINT32 calibrate (
        const ACE_UINT32 usec = 500000,
        const u_int iterations = 10
        );
    ACE_High_Res_Timer (void);
    ~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) const;
    void elapsed_time (ACE_hrtime_t &nanoseconds) const;
    void elapsed_time (struct timespec &) const;
    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) const;
    void elapsed_time_incr (ACE_hrtime_t &nanoseconds) const;
    void print_total (
        const char *message,
        const int iterations = 1,
        ACE_HANDLE handle = ACE_STDOUT
        ) const;
    void print_ave (
        const char *message,
        const int iterations = 1,
        ACE_HANDLE handle = ACE_STDOUT
        ) const;
    void dump (void) const;
    ACE_ALLOC_HOOK_DECLARE;
    ACE_OS::ACE_HRTIMER_GETTIME);
    static void hrtime_to_tv (
        ACE_Time_Value &tv,
        const ACE_hrtime_t hrt
        );
    static ACE_UINT32 get_cpuinfo (void);
  private:
    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_;
    static int global_scale_factor_status_;
};
```

## 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);
```

global\_scale\_factor\_ is set to gsf.  All High\_Res\_Timers use global\_scale\_factor\_.  This allows applications to set the scale factor just once for all High\_Res\_Timers.  Check High\_Res\_Timer.cpp for the default global\_scale\_factors for several platforms.  For many platforms (e.g., Solaris), the global\_scale\_factor\_ is set to 1000 so that scale\_factor need not be set.  Careful, a scale\_factor of 0 will cause division by zero exceptions.

```
static ACE_UINT32 global_scale_factor (void);
```

Returns the global\_scale\_factor.

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

Sets the global\_scale\_factor to the value in the env environment variable.  Returns 0 on success, -1 on failure.  Note if env points to string "0" (value zero), this call will fail. This is basically a no-op on CE because there is no concept of environment variable on CE.

```
static ACE_UINT32 calibrate (
    const ACE_UINT32 usec = 500000,
    const u_int iterations = 10
    );
```

Set (and return, for info) the global scale factor by sleeping for usec and counting the number of intervening clock cycles. Average over iterations of usec each.  On some platforms, such as Pentiums, this is called automatically during the first ACE\_High\_Res\_Timer construction with the default parameter values.  An application can override that by calling calibrate with any desired parameter values \_prior\_ to constructing the first ACE\_High\_Res\_Timer instance.

```
ACE_High_Res_Timer (void);
```

Initialize the timer.

```
~ACE_High_Res_Timer (void);
```

dtor.

```
void reset (void);
```

Reinitialize the timer.

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

Start timing.

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

Stop timing.

```
void elapsed_time (ACE_Time_Value &tv) const;
```

Set tv to the number of microseconds elapsed.

```
void elapsed_time (ACE_hrtime_t &nanoseconds) const;
```

Set nanoseconds to the number of nanoseconds elapsed.

```
void elapsed_time (struct timespec &) const;
```

Returns the elapsed (stop - start) time in a struct timespec (sec, nsec).

```
void elapsed_microseconds (ACE_hrtime_t &usecs) const;
```

Sets usecs to the elapsed (stop - start) time in microseconds.

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

Start incremental timing.

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

Stop incremental timing.

```
void elapsed_time_incr (ACE_Time_Value &tv) const;
```

Set tv to the number of microseconds elapsed between all calls to start\_incr and stop\_incr.

```
void elapsed_time_incr (ACE_hrtime_t &nanoseconds) const;
```

Set nsec to the number of nanoseconds elapsed between all calls to start\_incr and stop\_incr.

@@ 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
    ) const;
```

Print total time.  NOTE: only use print\_total if incremental timings had been used!

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

Print average time.

```
void dump (void) const;
```

Dump the state of an object.

```
ACE_ALLOC_HOOK_DECLARE;
```

Declare the dynamic allocation hooks.

```
ACE_OS::ACE_HRTIMER_GETTIME);
```

THIS FUNCTION IS DEPRECATED.  PLEASE USE ACE\_OS::gettimeofday INSTEAD!  Calls ACE\_High\_Res\_Timer::hrtime\_to\_tv passing ACE\_OS::gethrtime.  This function can be used to parameterize objects such as ACE\_Timer\_Queue::gettimeofday.  If global\_scale\_factor\_ is not set, and we're on a platform that requires global\_scale\_factor\_ (e.g., Win32), ACE\_OS::gettimeofday will be used instead of ACE\_OS::gethrtime. This allows applications on Intel to use High\_Res\_Timer even when global\_scale\_factor is not set.  However, setting the global\_scale\_factor\_ appropriately will result in the finest resolution possible.

```
static void hrtime_to_tv (ACE_Time_Value &tv, const ACE_hrtime_t hrt);
```

Converts an hrt to tv using global\_scale\_factor\_.

```
static ACE_UINT32 get_cpuinfo (void);
```

This is used to find out the Mhz of the machine for the scale factor.  If there are any problems getting it, we just return 1 (the default).

## AUTHOR

Doug Schmidt

## LIBRARY

ace