reactor-c
C Runtime for Lingua Franca
Loading...
Searching...
No Matches
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)   (t * 1LL)
 
#define NSECS(t)   (t * 1LL)
 
#define USEC(t)   (t * 1000LL)
 
#define USECS(t)   (t * 1000LL)
 
#define MSEC(t)   (t * 1000000LL)
 
#define MSECS(t)   (t * 1000000LL)
 
#define SEC(t)   (t * 1000000000LL)
 
#define SECS(t)   (t * 1000000000LL)
 
#define SECOND(t)   (t * 1000000000LL)
 
#define SECONDS(t)   (t * 1000000000LL)
 
#define MINUTE(t)   (t * 60000000000LL)
 
#define MINUTES(t)   (t * 60000000000LL)
 
#define HOUR(t)   (t * 3600000000000LL)
 
#define HOURS(t)   (t * 3600000000000LL)
 
#define DAY(t)   (t * 86400000000000LL)
 
#define DAYS(t)   (t * 86400000000000LL)
 
#define WEEK(t)   (t * 604800000000000LL)
 
#define WEEKS(t)   (t * 604800000000000LL)
 
#define NEVER   LLONG_MIN
 
#define FOREVER   LLONG_MAX
 
#define NEVER_TAG   (tag_t) { .time = LLONG_MIN, .microstep = 0u }
 
#define NEVER_TAG_INITIALIZER   { LLONG_MIN, 0u }
 
#define FOREVER_TAG   (tag_t) { .time = LLONG_MAX, .microstep = UINT_MAX }
 
#define FOREVER_TAG_INITIALIZER   { LLONG_MAX, UINT_MAX }
 
#define BILLION   1000000000LL
 
#define LF_TIME_BUFFER_LENGTH   80
 

Typedefs

typedef int64_t instant_t
 
typedef int64_t interval_t
 
typedef uint32_t microstep_t
 

Functions

tag_t lf_tag (void *env)
 
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)
 
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)
 
void lf_set_physical_clock_offset (interval_t offset)
 
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

Macro Definition Documentation

◆ BILLION

#define BILLION   1000000000LL

◆ DAY

#define DAY (   t)    (t * 86400000000000LL)

◆ DAYS

#define DAYS (   t)    (t * 86400000000000LL)

◆ FOREVER

#define FOREVER   LLONG_MAX

◆ FOREVER_TAG

#define FOREVER_TAG   (tag_t) { .time = LLONG_MAX, .microstep = UINT_MAX }

◆ FOREVER_TAG_INITIALIZER

#define FOREVER_TAG_INITIALIZER   { LLONG_MAX, UINT_MAX }

◆ HOUR

#define HOUR (   t)    (t * 3600000000000LL)

◆ HOURS

#define HOURS (   t)    (t * 3600000000000LL)

◆ LF_TIME_BUFFER_LENGTH

#define LF_TIME_BUFFER_LENGTH   80

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 55, for a total of 79. One more allows for a null terminator.

◆ MINUTE

#define MINUTE (   t)    (t * 60000000000LL)

◆ MINUTES

#define MINUTES (   t)    (t * 60000000000LL)

◆ MSEC

#define MSEC (   t)    (t * 1000000LL)

◆ MSECS

#define MSECS (   t)    (t * 1000000LL)

◆ NEVER

#define NEVER   LLONG_MIN

◆ NEVER_TAG

#define NEVER_TAG   (tag_t) { .time = LLONG_MIN, .microstep = 0u }

◆ NEVER_TAG_INITIALIZER

#define NEVER_TAG_INITIALIZER   { LLONG_MIN, 0u }

◆ NSEC

#define NSEC (   t)    (t * 1LL)

◆ NSECS

#define NSECS (   t)    (t * 1LL)

◆ SEC

#define SEC (   t)    (t * 1000000000LL)

◆ SECOND

#define SECOND (   t)    (t * 1000000000LL)

◆ SECONDS

#define SECONDS (   t)    (t * 1000000000LL)

◆ SECS

#define SECS (   t)    (t * 1000000000LL)

◆ USEC

#define USEC (   t)    (t * 1000LL)

◆ USECS

#define USECS (   t)    (t * 1000LL)

◆ WEEK

#define WEEK (   t)    (t * 604800000000000LL)

◆ WEEKS

#define WEEKS (   t)    (t * 604800000000000LL)

Typedef Documentation

◆ instant_t

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

◆ interval_t

Interval of time.

◆ 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
bufferA buffer long enough to contain a string like "9,223,372,036,854,775,807".
timeA 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
tagThe tag to increment.
intervalThe 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
tagThe tag to increment.
intervalThe 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:

return address
Definition hashmap.h:74

where each x is a string of numbers with commas inserted if needed every three numbers and unit is nanoseconds, microseconds, or milliseconds.

Parameters
bufferThe buffer into which to write the string.
timeThe time to write.
Returns
The number of characters written (not counting the null terminator).

◆ lf_set_physical_clock_offset()

void lf_set_physical_clock_offset ( interval_t  offset)

Set a fixed offset to the physical clock. After calling this, the value returned by lf_time_physical(void) and get_elpased_physical_time(void) will have this specified offset added to what it would have returned before the call.

◆ lf_tag()

tag_t lf_tag ( void env)

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

Parameters
envA pointer to the environment from which we want the current tag.

Return the current tag of a reactor. If NULL is passed to this function it will return the "global tag" of the runtime.

Parameters
selfA pointer to the environment of which you want the current tag
Returns
the current 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_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
envThe 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
envThe environment from which we want the elapsed logical time.
Returns
A time interval.

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

◆ 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.