Time utilities

Utilities to deal with time. More...

Macros
#define	csnip_time_AsTimespec(src)    csnip_time__AsTimespec((src))
	Convert the given time quantity to a struct timespec. More...
#define	csnip_time_Convert(src, target)    csnip_time__Convert((src), (target), csnip__tmp_ts)
	Convert a time. More...
#define	csnip_time_Sleep(amount, err)    csnip_time__Sleep((amount), (err), csnip__cerr)
	Sleep with subsecond precision. More...
#define	csnip_time_IsLess(time_a, time_b)
	Check if time_a < time_b. More...
#define	csnip_time_IsLessEqual(time_a, time_b)    csnip_time__IsLessEqual((time_a), (time_b))
	Check if time_a <= time_b. More...
#define	csnip_time_Add(time_a, time_b)
	Compute the sum of two times. More...
#define	csnip_time_Sub(time_a, time_b)
	Compute the difference of two times. More...

Functions
int	csnip_time_sleep (struct timespec ts)
	Sleep with subsecond precision.
int	csnip_time_is_less (struct timespec a, struct timespec b)
	Less-than comparison.
int	csnip_time_is_less_equal (struct timespec a, struct timespec b)
	Less-than-or-equal comparison.
struct timespec	csnip_time_add (struct timespec a, struct timespec b)
	Compute the sum of two durations.
struct timespec	csnip_time_sub (struct timespec a, struct timespec b)
	Compute the difference of two durations.

Conversion to struct timespec.
struct timespec	csnip_time_time_t_as_timespec (time_t t)
	time_t -> timespec
struct timespec	csnip_time_float_as_timespec (float f)
	float -> timespec
struct timespec	csnip_time_double_as_timespec (double d)
	double -> timespec
struct timespec	csnip_time_ldouble_as_timespec (long double d)
	long double -> timespec
struct timespec	csnip_time_timeval_as_timespec (struct timeval tv)
	timeval -> timespec

Conversion from struct timespec.
time_t	csnip_time_timespec_as_time_t (struct timespec ts)
	timespec -> time_t
float	csnip_time_timespec_as_float (struct timespec ts)
	timespec -> float
double	csnip_time_timespec_as_double (struct timespec ts)
	timespec -> double
long double	csnip_time_timespec_as_ldouble (struct timespec ts)
	timespec -> long double
struct timeval	csnip_time_timespec_as_timeval (struct timespec ts)
	timespec -> timeval

Detailed Description

The C language and POSIX have several ways to represent times, in particular time_t, struct timespec, struct timeval. Furthermore it is often convenient to use floating point values to represent times. This module provides a number of functions and macros to conveniently convert between the different time representations, as well as functions for sleeping, comparison of times, addition and subtraction of times. The module does not, however, get times; e.g., we do not duplicate functionality for clock_gettime().

The macro implementation is generic and can transparently handle the correct representation of time.

Representations. struct timespec and struct timeval have reasonably well defined semantics. In C11, the time_t representation is implementation defined. This module assumes that time_t has the POSIX encoding, i.e. it is the amount of seconds elapsed since the epoch (ignoring leap seconds), where the epoch is the same as the one struct timespec is anchored to. The macros further assume that time_t is not a floating point type. (We're not aware of any libc where time_t is a floating type, but the C standard does not exclude the possibility.) Time stored in floating point values is taken to count the number of seconds since the epoch.

Precision. struct timespec is considered the canonical representation of time; it has a resolution of 1 nanosecond. A double value can under some circumstances have better resolution than that, e.g. for the typical 64 bit double with 53 bit mantissa, a time smaller than 52 days has better precision than a nanosecond. This module does not take advantage of that fact, even those small doubles will still only have precision of struct timespec.

Assumptions. We assume that time_t and the tv_sec member of struct timespec have the same representation; the C11 standard does not guarantee this. The macros also assume C11's _Generic, and that time_t is not a float type.

Macro Definition Documentation

csnip_time_Add

#define csnip_time_Add	(		time_a,
			time_b
	)

Value:

    csnip_time_add( \
      csnip_time_AsTimespec(time_a), \
      csnip_time_AsTimespec(time_b))

Expression-macro to compute time_a + time_b. Any supported representation can be used for time_a and time_b and they don't need to be the same representation.

csnip_time_AsTimespec

#define csnip_time_AsTimespec

(

src

)

csnip_time__AsTimespec((src))

This expression-macro converts the time given in src to a timespec. It accepts struct timeval, time_t, or a floating point type as input type. Floating point numbers are considered as second values.

csnip_time_Convert

#define csnip_time_Convert	(		src,
			target
	)		csnip_time__Convert((src), (target), csnip__tmp_ts)

This statement-macro converts the time represented in src to the format of target and stores it in target. Acceptable types for both src and target are struct timespec, struct timeval, time_t, or a floating point value.

csnip_time_IsLess

#define csnip_time_IsLess	(		time_a,
			time_b
	)

Value:

    csnip_time_is_less( \
      csnip_time_AsTimespec(time_a), \
      csnip_time_AsTimespec(time_b))

Expression-macro to compare times. Any supported representation can be used for time_a and time_b and they don't need to be the same representation.

csnip_time_IsLessEqual

#define csnip_time_IsLessEqual	(		time_a,
			time_b
	)		csnip_time__IsLessEqual((time_a), (time_b))

Expression-macro to compare times. Any supported representation can be used for time_a and time_b and they don't need to be the same representation.

csnip_time_Sleep

#define csnip_time_Sleep	(		amount,
			err
	)		csnip_time__Sleep((amount), (err), csnip__cerr)

The sleep statement macro sleeps for the given amount; any supported representation can be used for amount.

csnip_time_Sub

#define csnip_time_Sub	(		time_a,
			time_b
	)

Value:

    csnip_time_sub( \
      csnip_time_AsTimespec(time_a), \
      csnip_time_AsTimespec(time_b))

Expression-macro to compute time_a - time_b. Any supported representation can be used for time_a and time_b and they don't need to be the same representation.