sopc_time_reference.h File Reference

A platform independent API to handle time reference management. More...

#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Macros
#define	SOPC_MONOTONIC_CLOCK   true
	the toolkit provide and use monotonic clock for time references (used for timers) Note: it is possible to set the clock as non monotonic defining variable on configuration. Otherwise default value is true.

Typedefs
typedef uint64_t	SOPC_TimeReference
typedef struct SOPC_HighRes_TimeReference	SOPC_HighRes_TimeReference

Functions
SOPC_TimeReference	SOPC_TimeReference_GetCurrent (void)
	return the current time reference
SOPC_TimeReference	SOPC_TimeReference_AddMilliseconds (SOPC_TimeReference timeRef, uint64_t ms)
	return the time reference corresponding to the given time reference incremented by the given duration in milliseconds
int8_t	SOPC_TimeReference_Compare (SOPC_TimeReference left, SOPC_TimeReference right)
	return the comparison of given time references
void	SOPC_HighRes_TimeReference_GetTime (SOPC_HighRes_TimeReference *t)
	Store the current time in t.
int64_t	SOPC_HighRes_TimeReference_DeltaUs (const SOPC_HighRes_TimeReference *tRef, const SOPC_HighRes_TimeReference *t)
	Compare two SOPC_HighRes_TimeReference elements into microseconds.
void	SOPC_HighRes_TimeReference_AddSynchedDuration (SOPC_HighRes_TimeReference *t, uint64_t duration_us, int32_t offset_us)
	Adds an offset to a SOPC_HighRes_TimeReference object, ensuring a specific time offset towards a synchronized clock within a periodic time window. The offset is measured regarding the dateTime Clock, thus implying that it is synchronized to some external PtP reference.
bool	SOPC_HighRes_TimeReference_IsExpired (const SOPC_HighRes_TimeReference *t, const SOPC_HighRes_TimeReference *now)
	Checks is a date is in the future (relatively to another date)
void	SOPC_HighRes_TimeReference_SleepUntil (const SOPC_HighRes_TimeReference *date)
	Precise sleep until specified date.
SOPC_HighRes_TimeReference *	SOPC_HighRes_TimeReference_Create (void)
	Create a new time reference.
void	SOPC_HighRes_TimeReference_Copy (SOPC_HighRes_TimeReference *to, const SOPC_HighRes_TimeReference *from)
	A copy of a non-NULL SOPC_HighRes_TimeReference structure.
void	SOPC_HighRes_TimeReference_Delete (SOPC_HighRes_TimeReference **t)
	Deletes a time reference.

Detailed Description

A platform independent API to handle time reference management.

Macro Definition Documentation

SOPC_MONOTONIC_CLOCK

#define SOPC_MONOTONIC_CLOCK   true

the toolkit provide and use monotonic clock for time references (used for timers) Note: it is possible to set the clock as non monotonic defining variable on configuration. Otherwise default value is true.

PubSub publications require a time that has finer resolution than C99 time_t. The OPC UA type Duration is a double representing ms delays between publications. It's resolution goes finer than the nanosecond resolution.

The SOPC_HighRes_TimeReference type should be defined to be as precise as possible to support sub-milliseconds publications.

Typedef Documentation

SOPC_TimeReference

typedef uint64_t SOPC_TimeReference

Provides a reference point in time (in milliseconds). This representation is only relevant when comparing two objects. It is mainly used to measure time intervals.

SOPC_HighRes_TimeReference

typedef struct SOPC_HighRes_TimeReference SOPC_HighRes_TimeReference

SOPC_TimeReference Provides a high resolution reference point in time. This representation is only relevant when comparing two objects. It is mainly used to measure time intervals. The granularity depends on OS specific capabilities.

Note

Each platform must provide the implementation of SOPC_HighRes_TimeReference and all related functions.

Function Documentation

SOPC_TimeReference_GetCurrent()

SOPC_TimeReference SOPC_TimeReference_GetCurrent

(

void

)

return the current time reference

Note: clock is monotonic if SOPC_MONOTONIC_CLOCK is true

Returns

the current time reference

SOPC_TimeReference_AddMilliseconds()

SOPC_TimeReference SOPC_TimeReference_AddMilliseconds	(	SOPC_TimeReference	timeRef,
		uint64_t	ms )

return the time reference corresponding to the given time reference incremented by the given duration in milliseconds

Parameters

timeRef	the time reference to be incremented
ms	the duration in milliseconds to use for increment

Returns

the new time reference incremented by the given duration or with the maximum value in case of overflow or NULL incase timerRef == NULL or new memory allocation failed

SOPC_TimeReference_Compare()

int8_t SOPC_TimeReference_Compare	(	SOPC_TimeReference	left,
		SOPC_TimeReference	right )

return the comparison of given time references

Parameters

left	the left time reference operand (NULL pointer considered less than any other value)
right	the right time reference operand (NULL pointer considered less than any other value)

Returns

-1 if left < right operand, 0 if left = right and 1 if left > right

SOPC_HighRes_TimeReference_GetTime()

void SOPC_HighRes_TimeReference_GetTime

(

SOPC_HighRes_TimeReference *

t

)

Store the current time in t.

Parameters

t	A time reference object. Nothing is done if NULL is passed.

Note

This function is not supposed to fail. (It is required at lowest level, including logging feature). In case of failure, the function should use SOPC_ASSERT.

SOPC_HighRes_TimeReference_DeltaUs()

int64_t SOPC_HighRes_TimeReference_DeltaUs	(	const SOPC_HighRes_TimeReference *	tRef,
		const SOPC_HighRes_TimeReference *	t )

Compare two SOPC_HighRes_TimeReference elements into microseconds.

Parameters

tRef	The reference time. Shall be non-NULL
t	A SOPC_HighRes_TimeReference value (current time is used if NULL).

Returns

the number of microseconds between the reference tRef and t. Positive if t is after tRef

SOPC_HighRes_TimeReference_AddSynchedDuration()

void SOPC_HighRes_TimeReference_AddSynchedDuration	(	SOPC_HighRes_TimeReference *	t,
		uint64_t	duration_us,
		int32_t	offset_us )

Adds an offset to a SOPC_HighRes_TimeReference object, ensuring a specific time offset towards a synchronized clock within a periodic time window. The offset is measured regarding the dateTime Clock, thus implying that it is synchronized to some external PtP reference.

For example, if duration_us is 100k (100ms) and offset_us is 20k (20 ms), and if we name "dtss" the "sub-second part of DateTime corresponding to returned \a t":

dtss = k * 100ms + 20ms (with k integer)

Parameters

t	A Non-null time reference
duration_us	The timeslice period (must be a divisor of 1 second, otherwise result is undefined) if offset_us is negative, then no window is used and the function simply adds duration_us to t
offset_us	The offset in microseconds in the time window. If no PtP source is synchronized, or if this offset is not used, it must be set to -1.

SOPC_HighRes_TimeReference_IsExpired()

bool SOPC_HighRes_TimeReference_IsExpired	(	const SOPC_HighRes_TimeReference *	t,
		const SOPC_HighRes_TimeReference *	now )

Checks is a date is in the future (relatively to another date)

Parameters

t	A non-NULL date
now	if non-NULL, this date will be compared to t. If NULL, the current date will be used instead.

Returns

true if t < now. Typically,

SOPC_HighRes_TimeReference_IsExpired(&t, NULL) 

returns true if t is in the past (event reached), and false if t is in the future.

SOPC_HighRes_TimeReference_SleepUntil()

void SOPC_HighRes_TimeReference_SleepUntil

(

const SOPC_HighRes_TimeReference *

date

)

Precise sleep until specified date.

Parameters

date	The date at which the function shall return. Cannot be NULL.

Note

This function is not supposed to fail. In case of failure, it is expected to call SOPC_ASSERT.

If date is in the past, the function yields but does not wait.

The calling thread must have appropriate scheduling policy and priority for precise timing.

SOPC_HighRes_TimeReference_Create()

SOPC_HighRes_TimeReference * SOPC_HighRes_TimeReference_Create

(

void

)

Create a new time reference.

Returns

A new time reference containing the current time

Note

Every object initialized by SOPC_HighRes_TimeReference_Create must be cleared by SOPC_HighRes_TimeReference_Delete.

SOPC_HighRes_TimeReference_Copy()

void SOPC_HighRes_TimeReference_Copy	(	SOPC_HighRes_TimeReference *	to,
		const SOPC_HighRes_TimeReference *	from )

A copy of a non-NULL SOPC_HighRes_TimeReference structure.

Parameters

to	Pointer to the destination. Function call ignored if NULL.
from	Pointer to the source. Function call ignored if NULL.

Note

This function is not supposed to fail. In case of failure, it is expected to call SOPC_ASSERT.

SOPC_HighRes_TimeReference_Delete()

void SOPC_HighRes_TimeReference_Delete

(

SOPC_HighRes_TimeReference **

t

)

Deletes a time reference.

Parameters

t	A reference returned by SOPC_HighRes_TimeReference_Create