Time

Sub-nanosecond integer time arithmetic, monotonic and wall-clock timestamps, calendar conversions and timespec / timeval bridging. More...

Modules
	Clocks
	Refcounted monotonic-clock object with one-shot timeout callbacks.

Macros
#define	R_CLOCK_TIME_IS_VALID(time)   (((RClockTime)(time)) != R_CLOCK_TIME_NONE)
	TRUE if time is not the R_CLOCK_TIME_NONE sentinel.
#define	R_NSECOND   RINT64_CONSTANT (1)
	One nanosecond, in RClockTime units.
#define	R_USECOND   RINT64_CONSTANT (1000)
	One microsecond, in RClockTime units.
#define	R_MSECOND   RINT64_CONSTANT (1000000)
	One millisecond, in RClockTime units.
#define	R_SECOND   RINT64_CONSTANT (1000000000)
	One second, in RClockTime units.
#define	R_MSEC_PER_SEC   1000
	Milliseconds per second.
#define	R_USEC_PER_SEC   1000000
	Microseconds per second.
#define	R_NSEC_PER_SEC   1000000000
	Nanoseconds per second.
#define	R_TIME_AS_HOURS(time)   ((time) / (R_SECOND * 60 * 60))
	Round time down to whole hours.
#define	R_TIME_AS_MINUTES(time)   ((time) / (R_SECOND * 60))
	Round time down to whole minutes.
#define	R_TIME_AS_SECONDS(time)   ((time) / R_SECOND)
	Round time down to whole seconds.
#define	R_TIME_AS_MSECONDS(time)   ((time) / R_MSECOND)
	Round time down to whole milliseconds.
#define	R_TIME_AS_USECONDS(time)   ((time) / R_USECOND)
	Round time down to whole microseconds.
#define	R_TIME_AS_NSECONDS(time)   ((time) / R_NSECOND)
	Round time down to whole nanoseconds (identity for RClockTime).
#define	R_CLOCK_DIFF(s, e)   (RClockTimeDiff)((e) - (s))
	Signed difference e - s as RClockTimeDiff.
#define	R_TIMESPEC_TO_TIME(ts)   (RClockTime)((ts).tv_sec * R_SECOND + (ts).tv_nsec * R_NSECOND)
	Convert a struct timespec to RClockTime.
#define	R_TIME_TO_TIMESPEC(t, ts)
	Write RClockTime t into struct timespec ts.
#define	R_TIME_TIMESPEC_INIT(t)
	Static initialiser for a struct timespec from RClockTime t.
#define	R_TIMEVAL_TO_TIME(tv)   (RClockTime)((tv).tv_sec * R_SECOND + (tv).tv_usec * R_USECOND)
	Convert a struct timeval to RClockTime.
#define	R_TIME_TO_TIMEVAL(t, tv)
	Write RClockTime t into struct timeval tv.
#define	R_TIME_TIMEVAL_INIT(t)
	Static initialiser for a struct timeval from RClockTime t.
#define	R_TIME_FORMAT   "u:%02u:%02u.%09u"
	printf conversion fragment matching R_TIME_ARGS.
#define	R_TIME_ARGS(t)
	Expand to the printf arguments for R_TIME_FORMAT.
#define	r_time_get_time_since_epoch()   r_time_get_unix_time ()
	Alias for r_time_get_unix_time.

Functions
RClockTime	r_time_get_ts_wallclock (void)
	Read the wall-clock real-time timestamp (CLOCK_REALTIME).
RClockTime	r_time_get_ts_monotonic (void)
	Read the monotonic timestamp (CLOCK_MONOTONIC); strictly non-decreasing across calls in a single boot.
RClockTime	r_time_get_ts_raw (void)
	Read the raw monotonic timestamp (CLOCK_MONOTONIC_RAW on Linux); not subject to NTP slewing.
ruint64	r_time_get_uptime (void)
	Return system uptime in seconds.
rboolean	r_time_is_leap_year (ruint16 year)
	TRUE if year is a Gregorian leap year. Years before 1753 always return FALSE.
ruint16	r_time_leap_years (ruint16 from, ruint16 to)
	Count leap years in the half-open range [from, to), with from clamped up to 1753.
rint8	r_time_days_in_month (ruint16 year, ruint8 month)
	Days in month (1-12) of year, accounting for leap years; -1 if month is out of range or year is before 1753.
ruint64	r_time_create_unix_time (ruint16 year, ruint8 month, ruint8 day, ruint8 hour, ruint8 minute, ruint8 second)
	Convert a broken-down date to a Unix timestamp (seconds since 1970-01-01 UTC).
rboolean	r_time_parse_unix_time (ruint64 time, ruint16 *year, ruint8 *month, ruint8 *day, ruint8 *hour, ruint8 *minute, ruint8 *second)
	Split a Unix timestamp into broken-down date components.
ruint64	r_time_get_unix_time (void)
	Return the current Unix timestamp (seconds since 1970-01-01 UTC).

Detailed Description

Sub-nanosecond integer time arithmetic, monotonic and wall-clock timestamps, calendar conversions and timespec / timeval bridging.

rlib represents time as RClockTime — a 64-bit unsigned count of nanoseconds. All durations and timestamps use this unit; the R_NSECOND / R_USECOND / R_MSECOND / R_SECOND constants are scale factors for converting from human-friendly units.

r_time_get_ts_monotonic is the right choice for elapsed-time measurements; r_time_get_ts_wallclock follows the system real-time clock (and can therefore jump backwards on adjustment).

Macro Definition Documentation

R_TIME_ARGS

#define R_TIME_ARGS

(

t

)

Value:

  R_CLOCK_TIME_IS_VALID (t) ? (ruint) R_TIME_AS_HOURS (t) : 99,             \
  R_CLOCK_TIME_IS_VALID (t) ? (ruint) R_TIME_AS_MINUTES (t) % 60 : 99,      \
  R_CLOCK_TIME_IS_VALID (t) ? (ruint) R_TIME_AS_SECONDS (t) % 60 : 99,      \
  R_CLOCK_TIME_IS_VALID (t) ? (ruint) ((t) % R_SECOND) : 999999999

Expand to the printf arguments for R_TIME_FORMAT.

R_TIME_FORMAT

#define R_TIME_FORMAT   "u:%02u:%02u.%09u"

printf conversion fragment matching R_TIME_ARGS.

The leading '' is omitted so the macro can be string-pasted after one, i.e. use it as "%" R_TIME_FORMAT to render a time like "0:01:23.456789012".

R_TIME_TIMESPEC_INIT

#define R_TIME_TIMESPEC_INIT

(

t

)

Value:

                                  { (rlong) ( (t) / R_SECOND),                \
                                  (rlong) (((t) % R_SECOND) / R_NSECOND) }

Static initialiser for a struct timespec from RClockTime t.

R_TIME_TIMEVAL_INIT

#define R_TIME_TIMEVAL_INIT

(

t

)

Value:

                                  { (rlong) ( (t) / R_SECOND),                \
                                  (rlong) (((t) % R_SECOND) / R_USECOND) }

Static initialiser for a struct timeval from RClockTime t.

R_TIME_TO_TIMESPEC

#define R_TIME_TO_TIMESPEC	(		t,
			ts
	)

Value:

R_STMT_START {                                                              \
  (ts).tv_sec  = (rlong) ( (t) / R_SECOND);                                 \
  (ts).tv_nsec = (rlong) (((t) % R_SECOND) / R_NSECOND);                    \
} R_STMT_END

Write RClockTime t into struct timespec ts.

R_TIME_TO_TIMEVAL

#define R_TIME_TO_TIMEVAL	(		t,
			tv
	)

Value:

R_STMT_START {                                                              \
  (tv).tv_sec  = (rlong) ( (t) / R_SECOND);                                 \
  (tv).tv_usec = (rlong) (((t) % R_SECOND) / R_USECOND);                    \
} R_STMT_END

Write RClockTime t into struct timeval tv.

Function Documentation

r_time_get_ts_wallclock()

RClockTime r_time_get_ts_wallclock

(

void

)

Read the wall-clock real-time timestamp (CLOCK_REALTIME).

Subject to NTP / admin adjustments; do not use for measuring elapsed time. Use r_time_get_ts_monotonic instead.

r_time_parse_unix_time()

rboolean r_time_parse_unix_time	(	ruint64	time,
		ruint16 *	year,
		ruint8 *	month,
		ruint8 *	day,
		ruint8 *	hour,
		ruint8 *	minute,
		ruint8 *	second
	)

Split a Unix timestamp into broken-down date components.

Returns

TRUE on success; on failure the out-parameters are left in an unspecified state.