Time module

Data Structures
struct	JUNO_TIMESTAMP_TAG
	Timestamp consisting of whole seconds and fixed-point subseconds. More...
struct	JUNO_TIME_API_TAG
	Vtable for time operations and conversions. More...

Macros
#define	JunoTime_TimeApiInit(Now, SleepTo, Sleep)
	Initialize a JUNO_TIME_API_T literal with default math/conversion impls.

Typedefs
typedef struct JUNO_TIME_API_TAG	JUNO_TIME_API_T
typedef struct JUNO_TIME_ROOT_TAG	JUNO_TIME_ROOT_T
typedef struct JUNO_TIMESTAMP_TAG	JUNO_TIMESTAMP_T
typedef uint32_t	JUNO_TIME_SECONDS_T
	Whole seconds component type.
typedef uint64_t	JUNO_TIME_MILLIS_T
	Milliseconds count type.
typedef uint64_t	JUNO_TIME_MICROS_T
	Microseconds count type.
typedef uint64_t	JUNO_TIME_NANOS_T
	Nanoseconds count type.
typedef uint32_t	JUNO_TIME_SUBSECONDS_T
	Subsecond fixed-point fraction type.

Functions
struct JUNO_TIME_ROOT_TAG	JUNO_MODULE_ROOT (JUNO_TIME_API_T, JUNO_MODULE_EMPTY)
	This is the Juno Time Module for all time time related operations.
	JUNO_MODULE_RESULT (JUNO_TIMESTAMP_RESULT_T, JUNO_TIMESTAMP_T)
	JUNO_MODULE_RESULT (JUNO_TIME_SECONDS_RESULT_T, JUNO_TIME_SECONDS_T)
	JUNO_MODULE_RESULT (JUNO_TIME_MILLIS_RESULT_T, JUNO_TIME_MILLIS_T)
	JUNO_MODULE_RESULT (JUNO_TIME_MICROS_RESULT_T, JUNO_TIME_MICROS_T)
	JUNO_MODULE_RESULT (JUNO_TIME_NANOS_RESULT_T, JUNO_TIME_NANOS_T)
	JUNO_MODULE_RESULT (JUNO_TIME_SUBSECONDS_RESULT_T, JUNO_TIME_SUBSECONDS_T)
JUNO_STATUS_T	JunoTime_AddTime (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T *ptRetTime, JUNO_TIMESTAMP_T tTimeToAdd)
	Add a duration to a timestamp in-place.
JUNO_STATUS_T	JunoTime_SubtractTime (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T *ptRetTime, JUNO_TIMESTAMP_T tTimeToSubtract)
	Subtract a duration from a timestamp in-place. If the subtraction would underflow (negative time), the result is saturated to 0 seconds and 0 subseconds, and JUNO_STATUS_INVALID_DATA_ERROR is returned.
JUNO_TIME_NANOS_RESULT_T	JunoTime_TimestampToNanos (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T tTime)
JUNO_TIME_MICROS_RESULT_T	JunoTime_TimestampToMicros (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T tTime)
JUNO_TIME_MILLIS_RESULT_T	JunoTime_TimestampToMillis (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T tTime)
JUNO_TIMESTAMP_RESULT_T	JunoTime_NanosToTimestamp (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIME_NANOS_T iNanos)
JUNO_TIMESTAMP_RESULT_T	JunoTime_MicrosToTimestamp (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIME_MICROS_T iMicros)
JUNO_TIMESTAMP_RESULT_T	JunoTime_MillisToTimestamp (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIME_MILLIS_T iMillis)
JUNO_RESULT_F64_T	JunoTime_TimestampToDouble (const JUNO_TIME_ROOT_T *ptTime, JUNO_TIMESTAMP_T tTimestamp)
JUNO_TIMESTAMP_RESULT_T	JunoTime_DoubleToTimestamp (const JUNO_TIME_ROOT_T *ptTime, double dTimestamp)
static bool	JunoTime_TimestampGreaterThan (JUNO_TIMESTAMP_T tLeft, JUNO_TIMESTAMP_T tRight)
	Compare timestamps (tLeft > tRight).
static bool	JunoTime_TimestampLessThan (JUNO_TIMESTAMP_T tLeft, JUNO_TIMESTAMP_T tRight)
	Compare timestamps (tLeft < tRight).
static bool	JunoTime_TimestampEquals (JUNO_TIMESTAMP_T tLeft, JUNO_TIMESTAMP_T tRight)
	Compare timestamps for equality.
static JUNO_STATUS_T	JunoTime_TimeInit (JUNO_TIME_ROOT_T *ptTime, const JUNO_TIME_API_T *ptApi, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, JUNO_USER_DATA_T *pvUserData)
	Initialize the time module root with API and failure handler.

Detailed Description

Declares the Juno Time module interface (JUNO_TIME_API_T) and provides reference implementations for common time math and conversions (add/subtract timestamps; convert between timestamp and nanos/micros/millis and double).

Notes on timestamp representation:

• JUNO_TIMESTAMP_T uses an integer seconds field (iSeconds) and an unsigned fractional field (iSubSeconds).
• The fractional field is interpreted as a fixed-point fraction of a second over the full-scale value giSUBSECS_MAX (all-ones of the type). That is, fraction = (double)iSubSeconds / giSUBSECS_MAX.
• Representations are not normalized: iSubSeconds == giSUBSECS_MAX is equivalent to adding 1 to iSeconds and setting iSubSeconds to 0. Callers should avoid constructing such non-canonical values unless they plan to normalize.

Conversion/rounding behavior (as implemented in juno_time.c):

• Timestamp -> integer nanos/micros/millis: rounds to the nearest integer using half-up rounding of the fractional part.
• double -> timestamp: truncates integer seconds, maps the fractional part to subseconds by truncation except for the maximal fractional bucket: when frac >= 1 - 1/giSUBSECS_MAX, rounds up to the next whole second with subseconds set to 0. Valid inputs satisfy 0.0 <= dTimestamp <= max(JUNO_TIME_SECONDS_T).

Error handling:

• Subtraction that would result in negative time returns JUNO_STATUS_INVALID_DATA_ERROR and saturates the result to 0 seconds and 0 subseconds.
• Integer conversions from timestamp (to nanos/micros/millis) detect overflow and return JUNO_STATUS_INVALID_DATA_ERROR.

Macro Definition Documentation

JunoTime_TimeApiInit

#define JunoTime_TimeApiInit	(		Now,
			SleepTo,
			Sleep
	)

Value:

{ \
    Now, \
    JunoTime_AddTime, \
    JunoTime_SubtractTime, \
    SleepTo, \
    Sleep, \
    JunoTime_TimestampToNanos, \
    JunoTime_TimestampToMicros, \
    JunoTime_TimestampToMillis, \
    JunoTime_NanosToTimestamp, \
    JunoTime_MicrosToTimestamp, \
    JunoTime_MillisToTimestamp, \
    JunoTime_TimestampToDouble, \
    JunoTime_DoubleToTimestamp, \
}

Initialize a JUNO_TIME_API_T literal with default math/conversion impls.

Parameters

Now	Implementation of current time provider.
SleepTo	Implementation of sleep-until.
Sleep	Implementation of sleep-for.

Typedef Documentation

JUNO_TIME_API_T

typedef struct JUNO_TIME_API_TAG JUNO_TIME_API_T

JUNO_TIME_MICROS_T

typedef uint64_t JUNO_TIME_MICROS_T

Microseconds count type.

JUNO_TIME_MILLIS_T

typedef uint64_t JUNO_TIME_MILLIS_T

Milliseconds count type.

JUNO_TIME_NANOS_T

typedef uint64_t JUNO_TIME_NANOS_T

Nanoseconds count type.

JUNO_TIME_ROOT_T

typedef struct JUNO_TIME_ROOT_TAG JUNO_TIME_ROOT_T

JUNO_TIME_SECONDS_T

typedef uint32_t JUNO_TIME_SECONDS_T

Whole seconds component type.

JUNO_TIME_SUBSECONDS_T

typedef uint32_t JUNO_TIME_SUBSECONDS_T

Subsecond fixed-point fraction type.

JUNO_TIMESTAMP_T

typedef struct JUNO_TIMESTAMP_TAG JUNO_TIMESTAMP_T

Function Documentation

JUNO_MODULE_RESULT() [1/6]

JUNO_MODULE_RESULT	(	JUNO_TIME_MICROS_RESULT_T	,
		JUNO_TIME_MICROS_T
	)

Result type carrying microseconds.

JUNO_MODULE_RESULT() [2/6]

JUNO_MODULE_RESULT	(	JUNO_TIME_MILLIS_RESULT_T	,
		JUNO_TIME_MILLIS_T
	)

Result type carrying milliseconds.

JUNO_MODULE_RESULT() [3/6]

JUNO_MODULE_RESULT	(	JUNO_TIME_NANOS_RESULT_T	,
		JUNO_TIME_NANOS_T
	)

Result type carrying nanoseconds.

JUNO_MODULE_RESULT() [4/6]

JUNO_MODULE_RESULT	(	JUNO_TIME_SECONDS_RESULT_T	,
		JUNO_TIME_SECONDS_T
	)

Result type carrying seconds.

JUNO_MODULE_RESULT() [5/6]

JUNO_MODULE_RESULT	(	JUNO_TIME_SUBSECONDS_RESULT_T	,
		JUNO_TIME_SUBSECONDS_T
	)

Result type carrying subseconds.

JUNO_MODULE_RESULT() [6/6]

JUNO_MODULE_RESULT	(	JUNO_TIMESTAMP_RESULT_T	,
		JUNO_TIMESTAMP_T
	)

Result type carrying a timestamp.

JUNO_MODULE_ROOT()

struct JUNO_TIME_ROOT_TAG JUNO_MODULE_ROOT	(	JUNO_TIME_API_T	,
		JUNO_MODULE_EMPTY
	)

This is the Juno Time Module for all time time related operations.

Certain operations regarding time math are implemented by LibJuno for module developers to include: JunoTime_AddTime JunoTime_SubtractTime JunoTime_TimestampToNanos JunoTime_TimestampToMicros JunoTime_TimestampToMillis JunoTime_NanosToTimestamp JunoTime_MicrosToTimestamp JunoTime_MillisToTimestamp

Time module root (holds API pointer and failure handler).

JunoTime_AddTime()

JUNO_STATUS_T JunoTime_AddTime	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T *	ptRetTime,
		JUNO_TIMESTAMP_T	tTimeToAdd
	)

Add a duration to a timestamp in-place.

Parameters

ptTime	Module pointer (used for error reporting).
ptRetTime	In/out timestamp to be updated.
tTimeToAdd	Duration to add.

Returns

JUNO_STATUS_SUCCESS on success.

JunoTime_DoubleToTimestamp()

JUNO_TIMESTAMP_RESULT_T JunoTime_DoubleToTimestamp	(	const JUNO_TIME_ROOT_T *	ptTime,
		double	dTimestamp
	)

JunoTime_MicrosToTimestamp()

JUNO_TIMESTAMP_RESULT_T JunoTime_MicrosToTimestamp	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIME_MICROS_T	iMicros
	)

JunoTime_MillisToTimestamp()

JUNO_TIMESTAMP_RESULT_T JunoTime_MillisToTimestamp	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIME_MILLIS_T	iMillis
	)

JunoTime_NanosToTimestamp()

JUNO_TIMESTAMP_RESULT_T JunoTime_NanosToTimestamp	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIME_NANOS_T	iNanos
	)

Conversions from integer durations to timestamp

JunoTime_SubtractTime()

JUNO_STATUS_T JunoTime_SubtractTime	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T *	ptRetTime,
		JUNO_TIMESTAMP_T	tTimeToSubtract
	)

Subtract a duration from a timestamp in-place. If the subtraction would underflow (negative time), the result is saturated to 0 seconds and 0 subseconds, and JUNO_STATUS_INVALID_DATA_ERROR is returned.

JunoTime_TimeInit()

static JUNO_STATUS_T JunoTime_TimeInit ( JUNO_TIME_ROOT_T *  ptTime, const JUNO_TIME_API_T *  ptApi, JUNO_FAILURE_HANDLER_T  pfcnFailureHandler, JUNO_USER_DATA_T *  pvUserData  )

inlinestatic

Initialize the time module root with API and failure handler.

JunoTime_TimestampEquals()

static bool JunoTime_TimestampEquals ( JUNO_TIMESTAMP_T  tLeft, JUNO_TIMESTAMP_T  tRight  )

inlinestatic

Compare timestamps for equality.

JunoTime_TimestampGreaterThan()

static bool JunoTime_TimestampGreaterThan ( JUNO_TIMESTAMP_T  tLeft, JUNO_TIMESTAMP_T  tRight  )

inlinestatic

Compare timestamps (tLeft > tRight).

JunoTime_TimestampLessThan()

static bool JunoTime_TimestampLessThan ( JUNO_TIMESTAMP_T  tLeft, JUNO_TIMESTAMP_T  tRight  )

inlinestatic

Compare timestamps (tLeft < tRight).

JunoTime_TimestampToDouble()

JUNO_RESULT_F64_T JunoTime_TimestampToDouble	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T	tTimestamp
	)

Conversions between timestamp and double (see rounding notes above)

JunoTime_TimestampToMicros()

JUNO_TIME_MICROS_RESULT_T JunoTime_TimestampToMicros	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T	tTime
	)

JunoTime_TimestampToMillis()

JUNO_TIME_MILLIS_RESULT_T JunoTime_TimestampToMillis	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T	tTime
	)

JunoTime_TimestampToNanos()

JUNO_TIME_NANOS_RESULT_T JunoTime_TimestampToNanos	(	const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_TIMESTAMP_T	tTime
	)

Conversions from timestamp to integer durations (round to nearest, half-up)