S2OPC OPCUA Toolkit
Macros | Typedefs | Functions
sopc_platform_time.h File Reference

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

#include "p_sopc_time.h"
#include <stdbool.h>
#include <stdint.h>
#include <time.h>
#include "sopc_builtintypes.h"
#include "sopc_enums.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. More...
 

Typedefs

typedef uint64_t SOPC_TimeReference
 

Functions

void SOPC_Sleep (unsigned int milliseconds)
 Suspend current thread execution for (at least) a millisecond interval. More...
 
SOPC_DateTime SOPC_Time_GetCurrentTimeUTC (void)
 return the current time in DateTime format which is 100 nanoseconds from 1601/01/01 00:00:00 UTC More...
 
SOPC_TimeReference SOPC_TimeReference_GetCurrent (void)
 return the current time reference More...
 
SOPC_ReturnStatus SOPC_Time_Breakdown_Local (time_t t, struct tm *tm)
 Breaks down a timestamp to its structured representation in local time. More...
 
SOPC_ReturnStatus SOPC_Time_Breakdown_UTC (time_t t, struct tm *tm)
 Breaks down a timestamp to its structured representation in UTC time. More...
 
bool SOPC_RealTime_GetTime (SOPC_RealTime *t)
 Store the current time in t. More...
 
int64_t SOPC_RealTime_DeltaUs (const SOPC_RealTime *tRef, const SOPC_RealTime *t)
 Compare two SOPC_RealTime elements into microseconds. More...
 
void SOPC_RealTime_AddSynchedDuration (SOPC_RealTime *t, uint64_t duration_us, int32_t offset_us)
 Adds an offset to a SOPC_RealTime 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. More...
 
bool SOPC_RealTime_IsExpired (const SOPC_RealTime *t, const SOPC_RealTime *now)
 Checks is a date is in the future (relatively to another date) More...
 
bool SOPC_RealTime_SleepUntil (const SOPC_RealTime *date)
 Precise sleep until specified date. More...
 
SOPC_RealTimeSOPC_RealTime_Create (const SOPC_RealTime *copy)
 Create a new time reference. More...
 
bool SOPC_RealTime_Copy (SOPC_RealTime *to, const SOPC_RealTime *from)
 A copy of a non-NULL SOPC_RealTime structure. More...
 
void SOPC_RealTime_Delete (SOPC_RealTime **t)
 Deletes a time reference. More...
 

Detailed Description

A platform independent API to handle time 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_RealTime type should be defined to be as precise as possible to support sub-milliseconds publications.

Typedef Documentation

◆ SOPC_TimeReference

typedef uint64_t SOPC_TimeReference

The platform-specific implementation of "p_time.h" shall provide the actual definition of

  • SOPC_RealTime to hold a RealTime information (date with no specific origin). It is only used to compute time differences. However, in case the system has an external PtP synchronization source, it is mandatory that this date is aligned to that PtP source clock modulo 1 second. The implementation must also use a monotonic clock in all platform implementation even if the system time gets back or forth (e.g. because of ntp).
  • all functions defined in this header except SOPC_RealTime_Create and SOPC_RealTime_Delete. Time reference type (milliseconds)

Function Documentation

◆ SOPC_Sleep()

void SOPC_Sleep ( unsigned int  milliseconds)

Suspend current thread execution for (at least) a millisecond interval.

Parameters
millisecondsThe milliseconds interval value for which execution must be suspended

◆ SOPC_Time_GetCurrentTimeUTC()

SOPC_DateTime SOPC_Time_GetCurrentTimeUTC ( void  )

return the current time in DateTime format which is 100 nanoseconds from 1601/01/01 00:00:00 UTC

Note: since the clock is not monotonic, it should not be used to measure elapsed time

Returns
the current time in DateTime format

◆ 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_Time_Breakdown_Local()

SOPC_ReturnStatus SOPC_Time_Breakdown_Local ( time_t  t,
struct tm *  tm 
)

Breaks down a timestamp to its structured representation in local time.

Parameters
tthe timestamp.
tmthe structured representation of the timestamp in local time.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_NOK in case of error.

◆ SOPC_Time_Breakdown_UTC()

SOPC_ReturnStatus SOPC_Time_Breakdown_UTC ( time_t  t,
struct tm *  tm 
)

Breaks down a timestamp to its structured representation in UTC time.

Parameters
tthe timestamp.
tmthe structured representation of the timestamp in UTC time.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_NOK in case of error.

◆ SOPC_RealTime_GetTime()

bool SOPC_RealTime_GetTime ( SOPC_RealTime t)

Store the current time in t.

Parameters
tA Non-null time reference
Returns
false if failed.

◆ SOPC_RealTime_DeltaUs()

int64_t SOPC_RealTime_DeltaUs ( const SOPC_RealTime tRef,
const SOPC_RealTime t 
)

Compare two SOPC_RealTime elements into microseconds.

Parameters
tRefThe reference time. Shall be non-NULL
tA SOPC_RealTime 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_RealTime_AddSynchedDuration()

void SOPC_RealTime_AddSynchedDuration ( SOPC_RealTime t,
uint64_t  duration_us,
int32_t  offset_us 
)

Adds an offset to a SOPC_RealTime 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
tA Non-null time reference
duration_usThe 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_usThe 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_RealTime_IsExpired()

bool SOPC_RealTime_IsExpired ( const SOPC_RealTime t,
const SOPC_RealTime now 
)

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

Parameters
tA non-NULL date
nowif non-NULL, this date will be compared to t. If NULL, the current date will be used instead.
Returns
true if t < now. Typically, returns true if t is in the past (event reached), and false if t is in the future.

◆ SOPC_RealTime_SleepUntil()

bool SOPC_RealTime_SleepUntil ( const SOPC_RealTime date)

Precise sleep until specified date.

Parameters
dateThe date at which the function shall return
Returns
true in case of success
Note
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_RealTime_Create()

SOPC_RealTime* SOPC_RealTime_Create ( const SOPC_RealTime copy)

Create a new time reference.

Parameters
copyA possibly NULL time reference.
Returns
A new time reference containing the current time if copy is NULL, or a copy of copy otherwise
Note
Every object initialized by SOPC_RealTime_Create must be cleared by SOPC_RealTime_Delete

◆ SOPC_RealTime_Copy()

bool SOPC_RealTime_Copy ( SOPC_RealTime to,
const SOPC_RealTime from 
)

A copy of a non-NULL SOPC_RealTime structure.

Parameters
toPointer to the destination
fromPointer to the source
Returns
true in case of success
false if from or to is NULL

◆ SOPC_RealTime_Delete()

void SOPC_RealTime_Delete ( SOPC_RealTime **  t)

Deletes a time reference.

Parameters
tA reference returned by SOPC_RealTime_Create
SOPC_RealTime_IsExpired
bool SOPC_RealTime_IsExpired(const SOPC_RealTime *t, const SOPC_RealTime *now)
Checks is a date is in the future (relatively to another date)