cyclecounter.h File Reference

#include "config.h"

Include dependency graph for cyclecounter.h:

This graph shows which files directly or indirectly include this file:

Description

High-resolution timestamp or CPU clock cycle counters.

After reading the current value with gmx_cycles_read() you can add or subtract these numbers as normal integers of type gmx_cycles_t.

Typedefs
typedef long	gmx_cycles_t
	Integer-like datatype for cycle counter values. More...

Functions
static __inline__ gmx_cycles_t	gmx_cycles_read (void)
	Read CPU cycle counter. More...
static __inline__ int	gmx_cycles_have_counter (void)
	Check if high-resolution cycle counters are available. More...
double	gmx_cycles_calibrate (double sampletime)
	Calculate number of seconds per cycle tick on host. More...

Typedef Documentation

typedef long gmx_cycles_t

Integer-like datatype for cycle counter values.

Depending on your system this will usually be something like long long, or a special cycle datatype from the system header files. It is NOT necessarily real processor cycles - many systems count in nanoseconds or a special external time register at fixed frequency (not the CPU freq.)

You can subtract or add gmx_cycle_t types just as normal integers, and if you run the calibration routine you can also multiply it with a factor to translate the cycle data to seconds.

Function Documentation

double gmx_cycles_calibrate

(

double

sampletime

)

Calculate number of seconds per cycle tick on host.

This routine runs a timer loop to calibrate the number of seconds per the units returned fro gmx_cycles_read().

Parameters

sampletime

Minimum real sample time. It takes some trial-and-error to find the correct delay loop size, so the total runtime of this routine is about twice this time.

Returns

Number of seconds per cycle unit. If it is not possible to calculate on this system (for whatever reason) the return value will be -1, so check that it is positive before using it.

static __inline__ int gmx_cycles_have_counter ( void  )

static

Check if high-resolution cycle counters are available.

Not all architectures provide any way to read timestep counters in the CPU, and on some it is broken. Although we refer to it as cycle counters, it is not necessarily given in units of cycles.

If you notice that system is missing, implement support for it, find out how to detect the system during preprocessing, and send us a patch.

Returns

1 if cycle counters are available, 0 if not.

Note

This functions not need to be in the header for performance reasons, but it is very important that we get exactly the same detection as for gmx_cycles_read() routines. If you compile the library with one compiler, and then use a different one when later linking to the library it might happen that the library supports cyclecounters but not the headers, or vice versa.

static __inline__ gmx_cycles_t gmx_cycles_read ( void  )

static

Read CPU cycle counter.

This routine returns an abstract datatype containing a cycle counter timestamp.

Returns

Opaque data corresponding to a cycle reading.

Please note that on most systems it takes several cycles to read and return the cycle counters. If you are measuring small intervals, you can compensate for this time by calling the routine twice and calculating what the difference is. Subtract this from your other measurements to get an accurate result.

Use gmx_cycles_difference() to get a real number corresponding to the difference between two gmx_cycles_t values returned from this routine.