tag.h File Reference

Time and tag definitions and functions for Lingua Franca. More...

#include <stdint.h>
#include <stddef.h>
#include <limits.h>

Go to the source code of this file.

Data Structures
struct	tag_t

Macros
#define	NSEC(t)
#define	NSECS(t)
#define	USEC(t)
#define	USECS(t)
#define	MSEC(t)
#define	MSECS(t)
#define	SEC(t)
#define	SECS(t)
#define	SECOND(t)
#define	SECONDS(t)
#define	MINUTE(t)
#define	MINUTES(t)
#define	HOUR(t)
#define	HOURS(t)
#define	DAY(t)
#define	DAYS(t)
#define	WEEK(t)
#define	WEEKS(t)
#define	NEVER   ((interval_t)LLONG_MIN)
#define	NEVER_MICROSTEP   0u
#define	FOREVER   ((interval_t)LLONG_MAX)
#define	FOREVER_MICROSTEP   UINT_MAX
#define	NEVER_TAG    (tag_t) { .time = NEVER, .microstep = NEVER_MICROSTEP }
#define	NEVER_TAG_INITIALIZER   {NEVER, NEVER_MICROSTEP}
#define	FOREVER_TAG    (tag_t) { .time = FOREVER, .microstep = FOREVER_MICROSTEP }
#define	FOREVER_TAG_INITIALIZER   {FOREVER, FOREVER_MICROSTEP}
#define	ZERO_TAG   (tag_t){.time = 0LL, .microstep = 0u}
#define	CHECK_TIMEOUT(start, duration)
#define	BILLION   ((instant_t)1000000000LL)
#define	LF_TIME_BUFFER_LENGTH   64

Typedefs
typedef int64_t	instant_t
typedef int64_t	interval_t
typedef uint32_t	microstep_t

Functions
tag_t	lf_tag (void *env)
tag_t	lf_tag_add (tag_t a, tag_t b)
instant_t	lf_time_add (instant_t a, interval_t b)
	Return the sum of an interval and an instant, saturating on overflow and underflow.
instant_t	lf_time_subtract (instant_t a, interval_t b)
	Return an instant minus an interval, saturating on overflow and underflow.
int	lf_tag_compare (tag_t tag1, tag_t tag2)
tag_t	lf_delay_tag (tag_t tag, interval_t interval)
tag_t	lf_delay_strict (tag_t tag, interval_t interval)
tag_t	lf_tag_latest_earlier (tag_t tag)
	Return the greatest tag earlier than the given tag.
instant_t	lf_time_logical (void *env)
interval_t	lf_time_logical_elapsed (void *env)
instant_t	lf_time_physical (void)
instant_t	lf_time_physical_elapsed (void)
instant_t	lf_time_start (void)
size_t	lf_readable_time (char *buffer, instant_t time)
size_t	lf_comma_separated_time (char *buffer, instant_t time)

Detailed Description

Time and tag definitions and functions for Lingua Franca.

Author

Edward A. Lee

Soroush Bateni

Hou Seng (Steven) Wong

Copyright

(c) 2020-2023, The University of California at Berkeley. License: BSD 2-clause

Macro Definition Documentation

BILLION

#define BILLION   ((instant_t)1000000000LL)

CHECK_TIMEOUT

#define CHECK_TIMEOUT	(		start,
			duration )

Value:

(lf_time_physical() > ((start) + (duration)))

DAY

#define DAY

(

t

)

Value:

((interval_t)(t * 86400000000000LL))

DAYS

#define DAYS

(

t

)

Value:

((interval_t)(t * 86400000000000LL))

FOREVER

#define FOREVER   ((interval_t)LLONG_MAX)

FOREVER_MICROSTEP

#define FOREVER_MICROSTEP   UINT_MAX

FOREVER_TAG

#define FOREVER_TAG    (tag_t) { .time = FOREVER, .microstep = FOREVER_MICROSTEP }

FOREVER_TAG_INITIALIZER

#define FOREVER_TAG_INITIALIZER   {FOREVER, FOREVER_MICROSTEP}

HOUR

#define HOUR

(

t

)

Value:

((interval_t)(t * 3600000000000LL))

HOURS

#define HOURS

(

t

)

Value:

((interval_t)(t * 3600000000000LL))

LF_TIME_BUFFER_LENGTH

#define LF_TIME_BUFFER_LENGTH   64

For user-friendly reporting of time values, the buffer length required. This is calculated as follows, based on 64-bit time in nanoseconds: Maximum number of weeks is 15,250 Maximum number of days is 6 Maximum number of hours is 23 Maximum number of minutes is 59 Maximum number of seconds is 59 Maximum number of nanoseconds is 999,999,999 Maximum number of microsteps is 4,294,967,295 Total number of characters for the above is 24. Text descriptions and spaces add an additional 30, for a total of 54. One more allows for a null terminator. Round up to a power of two.

MINUTE

#define MINUTE

(

t

)

Value:

((interval_t)(t * 60000000000LL))

MINUTES

#define MINUTES

(

t

)

Value:

((interval_t)(t * 60000000000LL))

MSEC

#define MSEC

(

t

)

Value:

((interval_t)(t * 1000000LL))

MSECS

#define MSECS

(

t

)

Value:

((interval_t)(t * 1000000LL))

NEVER

#define NEVER   ((interval_t)LLONG_MIN)

NEVER_MICROSTEP

#define NEVER_MICROSTEP   0u

NEVER_TAG

#define NEVER_TAG    (tag_t) { .time = NEVER, .microstep = NEVER_MICROSTEP }

NEVER_TAG_INITIALIZER

#define NEVER_TAG_INITIALIZER   {NEVER, NEVER_MICROSTEP}

NSEC

#define NSEC

(

t

)

Value:

((interval_t)(t * 1LL))

NSECS

#define NSECS

(

t

)

Value:

((interval_t)(t * 1LL))

SEC

#define SEC

(

t

)

Value:

((interval_t)(t * 1000000000LL))

SECOND

#define SECOND

(

t

)

Value:

((interval_t)(t * 1000000000LL))

SECONDS

#define SECONDS

(

t

)

Value:

((interval_t)(t * 1000000000LL))

SECS

#define SECS

(

t

)

Value:

((interval_t)(t * 1000000000LL))

USEC

#define USEC

(

t

)

Value:

((interval_t)(t * 1000LL))

USECS

#define USECS

(

t

)

Value:

((interval_t)(t * 1000LL))

WEEK

#define WEEK

(

t

)

Value:

((interval_t)(t * 604800000000000LL))

WEEKS

#define WEEKS

(

t

)

Value:

((interval_t)(t * 604800000000000LL))

ZERO_TAG

#define ZERO_TAG   (tag_t){.time = 0LL, .microstep = 0u}

Typedef Documentation

instant_t

typedef int64_t instant_t

Time instant. Both physical and logical times are represented using this typedef.

interval_t

typedef int64_t interval_t

Interval of time.

microstep_t

typedef uint32_t microstep_t

Microstep instant.

Function Documentation

lf_comma_separated_time()

size_t lf_comma_separated_time	(	char *	buffer,
		instant_t	time )

Print a non-negative time value in nanoseconds with commas separating thousands into the specified buffer. Ideally, this would use the locale to use periods if appropriate, but I haven't found a sufficiently portable way to do that.

Parameters

buffer	A buffer long enough to contain a string like "9,223,372,036,854,775,807".
time	A time value.

Returns

The number of characters written (not counting the null terminator).

lf_delay_strict()

tag_t lf_delay_strict	(	tag_t	tag,
		interval_t	interval )

Return the latest tag strictly less than the specified tag plus the interval, unless tag is NEVER or interval is negative (including NEVER), in which case return the tag unmodified. Any interval less than 0 (including NEVER) is interpreted as "no delay", whereas an interval equal to 0 is interpreted as one microstep delay. If the time sum overflows, saturate the time value at FOREVER. For example:

• if tag = (t, 0) and interval = 10, return (t + 10 - 1, UINT_MAX)
• if tag = (t, 0) and interval = 0, return (t, 0)
• if tag = (t, 0) and interval = NEVER, return (t, 0)
• if tag = (FOREVER, 0) and interval = 10, return (FOREVER, 0)

Parameters

tag	The tag to increment.
interval	The time interval.

lf_delay_tag()

tag_t lf_delay_tag	(	tag_t	tag,
		interval_t	interval )

Delay a tag by the specified time interval to realize the "after" keyword. Any interval less than 0 (including NEVER) is interpreted as "no delay", whereas an interval equal to 0 is interpreted as one microstep delay. If the time field of the tag is NEVER or the interval is negative, return the unmodified tag. If the time interval is 0LL, add one to the microstep, leave the time field alone, and return the result. Otherwise, add the interval to the time field of the tag and reset the microstep to 0. If the sum overflows, saturate the time value at FOREVER. For example:

• if tag = (t, 0) and interval = 10, return (t + 10, 0)
• if tag = (t, 0) and interval = 0, return (t, 1)
• if tag = (t, 0) and interval = NEVER, return (t, 0)
• if tag = (FOREVER, 0) and interval = 10, return (FOREVER, 0)

Parameters

tag	The tag to increment.
interval	The time interval.

lf_readable_time()

size_t lf_readable_time	(	char *	buffer,
		instant_t	time )

Store into the specified buffer a string giving a human-readable rendition of the specified time. The buffer must have length at least equal to LF_TIME_BUFFER_LENGTH. The format is:

x weeks, x d, x hr, x min, x s, x unit

where each x is a string of numbers with commas inserted if needed every three numbers and unit is ns, us, or ms.

Parameters

buffer	The buffer into which to write the string.
time	The time to write.

Returns

The number of characters written (not counting the null terminator).

lf_tag()

tag_t lf_tag

(

void *

env

)

Return the current tag, a logical time, microstep pair.

Parameters

env	A pointer to the environment from which we want the current tag.

lf_tag_add()

tag_t lf_tag_add	(	tag_t	a,
		tag_t	b )

Add two tags. If either tag has has NEVER or FOREVER in its time field, then return NEVER_TAG or FOREVER_TAG, respectively. Also return NEVER_TAG or FOREVER_TAG if the result underflows or overflows when adding the times. If the microstep overflows, also return FOREVER_TAG. If the time field of the second tag is greater than 0, then the microstep of the first tag is reset to 0 before adding. This models the delay semantics in LF and makes this addition operation non-commutative.

Parameters

a	The first tag.
b	The second tag.

lf_tag_compare()

int lf_tag_compare	(	tag_t	tag1,
		tag_t	tag2 )

Compare two tags. Return -1 if the first is less than the second, 0 if they are equal, and +1 if the first is greater than the second. A tag is greater than another if its time is greater or if its time is equal and its microstep is greater.

Parameters

tag1
tag2

Returns

-1, 0, or 1 depending on the relation.

lf_tag_latest_earlier()

tag_t lf_tag_latest_earlier

(

tag_t

tag

)

Return the greatest tag earlier than the given tag.

If the given tag is FOREVER_TAG or NEVER_TAG, however, just return the given tag.

Parameters

tag

The tag.

lf_time_add()

instant_t lf_time_add	(	instant_t	a,
		interval_t	b )

Return the sum of an interval and an instant, saturating on overflow and underflow.

Parameters

a
b

Returns

instant_t

lf_time_logical()

instant_t lf_time_logical

(

void *

env

)

Return the current logical time in nanoseconds. On many platforms, this is the number of nanoseconds since January 1, 1970, but it is actually platform dependent.

Parameters

env	The environment from which we want the current logical time.

Returns

A time instant.

lf_time_logical_elapsed()

interval_t lf_time_logical_elapsed

(

void *

env

)

Return the elapsed logical time in nanoseconds since the start of execution.

Parameters

env	The environment from which we want the elapsed logical time.

Returns

A time interval.

lf_time_physical()

instant_t lf_time_physical

(

void

)

Return the current physical time in nanoseconds. On many platforms, this is the number of nanoseconds since January 1, 1970, but it is actually platform dependent.

Returns

A time instant.

lf_time_physical_elapsed()

instant_t lf_time_physical_elapsed

(

void

)

Return the elapsed physical time in nanoseconds. This is the time returned by lf_time_physical(void) minus the physical start time as measured by lf_time_physical(void) when the program was started.

lf_time_start()

instant_t lf_time_start

(

void

)

Return the physical and logical time of the start of execution in nanoseconds. On many platforms, this is the number of nanoseconds since January 1, 1970, but it is actually platform dependent.

Returns

A time instant.

lf_time_subtract()

instant_t lf_time_subtract	(	instant_t	a,
		interval_t	b )

Return an instant minus an interval, saturating on overflow and underflow.

Parameters

a
b

Returns

instant_t