High Resolution Timestamp

Functions
pj_status_t	pj_gettickcount (pj_time_val *tv)
pj_status_t	pj_get_timestamp (pj_timestamp *ts)
pj_status_t	pj_get_timestamp_freq (pj_timestamp *freq)
void	pj_set_timestamp32 (pj_timestamp *t, pj_uint32_t hi, pj_uint32_t lo)
int	pj_cmp_timestamp (const pj_timestamp *t1, const pj_timestamp *t2)
void	pj_add_timestamp (pj_timestamp *t1, const pj_timestamp *t2)
void	pj_add_timestamp32 (pj_timestamp *t1, pj_uint32_t t2)
void	pj_sub_timestamp (pj_timestamp *t1, const pj_timestamp *t2)
void	pj_sub_timestamp32 (pj_timestamp *t1, pj_uint32_t t2)
pj_int32_t	pj_timestamp_diff32 (const pj_timestamp *t1, const pj_timestamp *t2)
pj_time_val	pj_elapsed_time (const pj_timestamp *start, const pj_timestamp *stop)
pj_uint32_t	pj_elapsed_msec (const pj_timestamp *start, const pj_timestamp *stop)
pj_uint64_t	pj_elapsed_msec64 (const pj_timestamp *start, const pj_timestamp *stop)
pj_uint32_t	pj_elapsed_usec (const pj_timestamp *start, const pj_timestamp *stop)
pj_uint32_t	pj_elapsed_nanosec (const pj_timestamp *start, const pj_timestamp *stop)
pj_uint32_t	pj_elapsed_cycle (const pj_timestamp *start, const pj_timestamp *stop)

Detailed Description

PJLIB provides High Resolution Timestamp API to access highest resolution timestamp value provided by the platform. The API is usefull to measure precise elapsed time, and can be used in applications such as profiling.

The timestamp value is represented in cycles, and can be related to normal time (in seconds or sub-seconds) using various functions provided.

Examples

For examples, please see:

• Test: Sleep, Time, and Timestamp
• Test: Timestamp

Function Documentation

pj_add_timestamp()

void pj_add_timestamp	(	pj_timestamp *	t1,
		const pj_timestamp *	t2
	)

Add timestamp t2 to t1.

Parameters

t1	t1.
t2	t2.

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_add_timestamp32()

void pj_add_timestamp32	(	pj_timestamp *	t1,
		pj_uint32_t	t2
	)

Add timestamp t2 to t1.

Parameters

t1	t1.
t2	t2.

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_cmp_timestamp()

int pj_cmp_timestamp	(	const pj_timestamp *	t1,
		const pj_timestamp *	t2
	)

Compare timestamp t1 and t2.

Parameters

t1	t1.
t2	t2.

Returns

-1 if (t1 < t2), 1 if (t1 > t2), or 0 if (t1 == t2)

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_elapsed_cycle()

pj_uint32_t pj_elapsed_cycle	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Calculate the elapsed time in 32-bit cycles. This function calculates the elapsed time using highest precision calculation that is available for current platform, considering whether floating point or 64-bit precision arithmetic is available. For maximum portability, application should prefer to use this function rather than calculating the elapsed time by itself.

Parameters

start	The starting timestamp.
stop	The end timestamp.

Returns

Elapsed time in cycles.

See also

pj_elapsed_usec(), pj_elapsed_time(), pj_elapsed_nanosec()

pj_elapsed_msec()

pj_uint32_t pj_elapsed_msec	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Calculate the elapsed time as 32-bit miliseconds. This function calculates the elapsed time using highest precision calculation that is available for current platform, considering whether floating point or 64-bit precision arithmetic is available. For maximum portability, application should prefer to use this function rather than calculating the elapsed time by itself.

Parameters

start	The starting timestamp.
stop	The end timestamp.

Returns

Elapsed time in milisecond.

See also

pj_elapsed_time(), pj_elapsed_cycle(), pj_elapsed_nanosec()

pj_elapsed_msec64()

pj_uint64_t pj_elapsed_msec64	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Variant of pj_elapsed_msec() which returns 64bit value.

pj_elapsed_nanosec()

pj_uint32_t pj_elapsed_nanosec	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Calculate the elapsed time in 32-bit nanoseconds. This function calculates the elapsed time using highest precision calculation that is available for current platform, considering whether floating point or 64-bit precision arithmetic is available. For maximum portability, application should prefer to use this function rather than calculating the elapsed time by itself.

Parameters

start	The starting timestamp.
stop	The end timestamp.

Returns

Elapsed time in nanoseconds.

See also

pj_elapsed_time(), pj_elapsed_cycle(), pj_elapsed_usec()

pj_elapsed_time()

pj_time_val pj_elapsed_time	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Calculate the elapsed time, and store it in pj_time_val. This function calculates the elapsed time using highest precision calculation that is available for current platform, considering whether floating point or 64-bit precision arithmetic is available. For maximum portability, application should prefer to use this function rather than calculating the elapsed time by itself.

Parameters

start	The starting timestamp.
stop	The end timestamp.

Returns

Elapsed time as pj_time_val.

See also

pj_elapsed_usec(), pj_elapsed_cycle(), pj_elapsed_nanosec()

pj_elapsed_usec()

pj_uint32_t pj_elapsed_usec	(	const pj_timestamp *	start,
		const pj_timestamp *	stop
	)

Calculate the elapsed time in 32-bit microseconds. This function calculates the elapsed time using highest precision calculation that is available for current platform, considering whether floating point or 64-bit precision arithmetic is available. For maximum portability, application should prefer to use this function rather than calculating the elapsed time by itself.

Parameters

start	The starting timestamp.
stop	The end timestamp.

Returns

Elapsed time in microsecond.

See also

pj_elapsed_time(), pj_elapsed_cycle(), pj_elapsed_nanosec()

pj_get_timestamp()

pj_status_t pj_get_timestamp

(

pj_timestamp *

ts

)

Acquire high resolution timer value. The time value are stored in cycles.

Parameters

ts	High resolution timer value.

Returns

PJ_SUCCESS or the appropriate error code.

See also

pj_get_timestamp_freq().

pj_get_timestamp_freq()

pj_status_t pj_get_timestamp_freq

(

pj_timestamp *

freq

)

Get high resolution timer frequency, in cycles per second.

Parameters

freq	Timer frequency, in cycles per second.

Returns

PJ_SUCCESS or the appropriate error code.

pj_gettickcount()

pj_status_t pj_gettickcount

(

pj_time_val *

tv

)

Get monotonic time since some unspecified starting point.

Parameters

tv	Variable to store the result.

Returns

PJ_SUCCESS if successful.

pj_set_timestamp32()

void pj_set_timestamp32	(	pj_timestamp *	t,
		pj_uint32_t	hi,
		pj_uint32_t	lo
	)

Set timestamp from 32bit values.

Parameters

t	The timestamp to be set.
hi	The high 32bit part.
lo	The low 32bit part.

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_sub_timestamp()

void pj_sub_timestamp	(	pj_timestamp *	t1,
		const pj_timestamp *	t2
	)

Substract timestamp t2 from t1.

Parameters

t1	t1.
t2	t2.

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_sub_timestamp32()

void pj_sub_timestamp32	(	pj_timestamp *	t1,
		pj_uint32_t	t2
	)

Substract timestamp t2 from t1.

Parameters

t1	t1.
t2	t2.

References pj_timestamp::hi, pj_timestamp::lo, and pj_timestamp::u32.

pj_timestamp_diff32()

pj_int32_t pj_timestamp_diff32	(	const pj_timestamp *	t1,
		const pj_timestamp *	t2
	)

Get the timestamp difference between t2 and t1 (that is t2 minus t1), and return a 32bit signed integer difference.

References pj_timestamp::lo, and pj_timestamp::u32.