PsyTime.h File Reference

CMSDK time: µs-resolution 64-bit timestamps and the Time Mapping Constant (TMC). More...

#include "Types.h"
#include "sys/timeb.h"

Include dependency graph for PsyTime.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cmlabs::PsyDateAndTime
	A PsyTime timestamp or time difference broken down into calendar fields. More...

Namespaces
namespace	cmlabs

Macros
#define	USEC_YEAR_0_TO_1970   62167305600000000L
	Microseconds between year 0000 and the Unix epoch (1970-01-01).
#define	SECS_PER_YEAR   31536000
	Seconds in a (non-leap) 365-day year.
#define	SECS_PER_MONTH   2629744
	Average seconds per Gregorian month (365.2425/12 days).
#define	SECS_PER_WEEK   604800
	Seconds per week.
#define	SECS_PER_DAY   86400
	Seconds per day.
#define	SECS_PER_HOUR   3600
	Seconds per hour.
#define	SECS_PER_MIN   60
	Seconds per minute.
#define	TIME_YEAR_1970   62167305600000000L
	Same value as USEC_YEAR_0_TO_1970: the PsyTime timestamp of 1970-01-01 00:00:00 UTC.
Millisecond duration constants
Common durations expressed in milliseconds. Warning MINUTE_MS..WEEK_MS expand as SECS_PER_X * 1000 without parentheses — beware when used inside larger expressions.
#define	SECOND_MS   1000
#define	MINUTE_MS   SECS_PER_MIN * 1000
#define	HOUR_MS   SECS_PER_HOUR * 1000
#define	DAY_MS   SECS_PER_DAY * 1000
#define	WEEK_MS   SECS_PER_WEEK * 1000
#define	MONTH_MS   (uint64)SECS_PER_MONTH * 1000
#define	YEAR_MS   (uint64)SECS_PER_YEAR * 1000
Microsecond duration constants
Common durations expressed in microseconds — the native PsyTime unit.
#define	SECOND_US   (uint64)1000000
#define	MINUTE_US   (uint64)SECS_PER_MIN * 1000000
#define	HOUR_US   (uint64)SECS_PER_HOUR * 1000000
#define	DAY_US   (uint64)SECS_PER_DAY * 1000000
#define	WEEK_US   (uint64)SECS_PER_WEEK * 1000000
#define	MONTH_US   (uint64)SECS_PER_MONTH * 1000000
#define	YEAR_US   (uint64)SECS_PER_YEAR * 1000000
PSY* duration aliases
Preferred spelling of the µs duration constants in application code, e.g. 5*PSYSECOND.
#define	PSYSECOND   SECOND_US
#define	PSYMINUTE   MINUTE_US
#define	PSYHOUR   HOUR_US
#define	PSYDAY   DAY_US
#define	PSYWEEK   WEEK_US
#define	PSYMONTH   MONTH_US
#define	PSYYEAR   YEAR_US
TMC roles and sync interval
#define	TMC_MASTER   0
	This node is the time master; others sync to it.
#define	TMC_SLAVE   1
	This node slaves its clock to a remote master.
#define	TMC_SYNC_INTERVAL   60000000
	Re-sync interval in µs (1 minute).

Functions
uint64	cmlabs::GetTimeNow ()
	Return the current absolute time (µs since year 0) according to the TMC.
uint64	cmlabs::SyncToHardwareClock ()
	Recompute the Time Mapping Constant by anchoring the monotonic clock to the wall clock.
bool	cmlabs::SetCurrentNetSyncDif (int64 netTimeDif)
	Set the network time difference for a slave node so its GetTimeNow() matches the master.
bool	cmlabs::SetCurrentTimeSyncData (uint64 tmc, int64 netTimeAdjust)
	Install externally computed sync data (e.g.
bool	cmlabs::GetCurrentTimeSyncData (uint64 &tmc, int64 &netTimeAdjust)
	Read the current sync data.
uint64	cmlabs::EstNextTMCWrap ()
	Estimate when the underlying hardware counter will next wrap around.
int64	cmlabs::GetTimeAge (uint64 t)
	Age of a timestamp relative to now.
int32	cmlabs::GetTimeAgeMS (uint64 t)
	Age of a timestamp relative to now, in milliseconds.
uint64	cmlabs::GetTimeFromString (const char *str)
	Parse a textual date/time into a PsyTime timestamp.
uint32	cmlabs::GetHTTPTime (uint64 time, char *buffer, uint32 size)
	Format a timestamp as an HTTP-date (RFC 7231) string, e.g.
uint64	cmlabs::GetTimeFromPsyDateAndTime (struct PsyDateAndTime &tad)
	Convert a broken-down PsyDateAndTime back into a µs timestamp.
uint32	cmlabs::GetTimeOffsetGMT ()
struct PsyDateAndTime	cmlabs::GetDateAndTime (uint64 t, bool local=true)
	Break a timestamp into calendar fields.
struct PsyDateAndTime	cmlabs::GetDateAndTimeUTC (uint64 t)
	Break a timestamp into calendar fields in UTC.
struct PsyDateAndTime	cmlabs::GetTimeDifference (uint64 t1, uint64 t2)
	Express the difference t1 - t2 as calendar fields (negative flag set when t2 > t1).
struct PsyDateAndTime	cmlabs::GetTimeDifference (int64 dif)
	Express a signed µs difference as calendar fields.
uint64	cmlabs::FTime2PsyTime (uint64 t)
	Convert an ftime-style value (ms since Unix epoch) to a PsyTime µs timestamp.
bool	cmlabs::PsyTime_UnitTest ()
	Run the PsyTime unit tests.
char* time formatters
Format timestamps into newly allocated char buffers. Warning Ownership: each of these allocates a fresh 1024-byte buffer with new char[] and returns it — the CALLER must delete [] the result or it leaks. Prefer the std::string variants below, which have no such footgun. Common parameters: t timestamp in µs; local = local time vs UTC; us / ms = include microseconds / milliseconds in the output.
char *	cmlabs::PrintTime (uint64 t, bool local=true, bool us=true, bool ms=true)
	Full date + time-of-day.
char *	cmlabs::PrintTimeOnly (uint64 t, bool local=true, bool us=true, bool ms=true)
	Time-of-day only.
char *	cmlabs::PrintTimeDif (uint64 t, bool us=true, bool ms=true)
	Format a µs duration with scale-adaptive units: "250us", "1.500ms", "2.750s", "2m 3s", "01:02:03", "3 days 01:02:03".
char *	cmlabs::PrintDate (uint64 t, bool local=true)
	Date only, human-readable.
char *	cmlabs::PrintDateSortable (uint64 t, bool local=true)
	Date only, sortable (e.g.
char *	cmlabs::PrintDateSortableDelimiter (uint64 t, const char *del, bool local=true)
	Sortable date with custom field delimiter.
char *	cmlabs::PrintTimeSortable (uint64 t, bool local)
	Sortable date+time, second resolution.
char *	cmlabs::PrintTimeSortableMillisec (uint64 t, bool local)
	Sortable date+time with milliseconds.
char *	cmlabs::PrintTimeSortableMicrosec (uint64 t, bool local)
	Sortable date+time with microseconds.
std::string time formatters
Thread-safe, leak-free equivalents of the char* formatters above (they wrap the char* variants and free the buffer); same parameter conventions (t µs timestamp, local, us, ms). Preferred in application code. uint64 t = GetTimeNow(); std::string full = PrintTimeString(t); // "21/07/2026 15:30:02.123.456" std::string clock = PrintTimeOnlyString(t, true, false, true); // "15:30:02.123" std::string sortable = PrintTimeSortableMillisecString(t); // "20260721-153002.123" std::string logname = PrintDateStringSortableDelimiter(t, "-"); // "2026-07-21" std::string age = PrintTimeDifString(GetTimeAge(msgTime)); // e.g. "2m 3s"
std::string	cmlabs::PrintTimeNowString (bool local=true, bool us=true, bool ms=true)
	Format GetTimeNow().
std::string	cmlabs::PrintTimeString (uint64 t, bool local=true, bool us=true, bool ms=true)
std::string	cmlabs::PrintTimeOnlyString (uint64 t, bool local=true, bool us=true, bool ms=true)
std::string	cmlabs::PrintTimeDifString (uint64 t, bool us=true, bool ms=true)
std::string	cmlabs::PrintDateString (uint64 t, bool local=true)
std::string	cmlabs::PrintDateStringSortable (uint64 t, bool local=true)
std::string	cmlabs::PrintDateStringSortableDelimiter (uint64 t, const char *del, bool local=true)
std::string	cmlabs::PrintTimeSortableString (uint64 t, bool local=true)
	Sortable date+time, second resolution.
std::string	cmlabs::PrintTimeSortableMillisecString (uint64 t, bool local=true)
	Sortable date+time with milliseconds.
std::string	cmlabs::PrintTimeSortableMicrosecString (uint64 t, bool local=true)
	Sortable date+time with microseconds.

Variables
static char	cmlabs::PsyDays [][5] = {"None", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"}
	Abbreviated weekday names indexed 1..7 (Mon..Sun); index 0 is "None".
static char	cmlabs::PsyDaysFull [][10] = {"None", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"}
	Full weekday names indexed 1..7 (Monday..Sunday); index 0 is "None".
static char	cmlabs::PsyMonths [][5] = {"None", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}
	Abbreviated month names indexed 1..12 (Jan..Dec); index 0 is "None".
static char	cmlabs::PsyMonthsFull [][10] = {"None", "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
	Full month names indexed 1..12; index 0 is "None".
static uint64	cmlabs::CurrentTMC = 0
	Current Time Mapping Constant (µs offset from monotonic clock to absolute PsyTime).
static uint8	cmlabs::CurrentTMCMode = TMC_MASTER
	Current TMC role: TMC_MASTER or TMC_SLAVE.
static uint64	cmlabs::LastTMCSync = 0
	PsyTime timestamp of the last hardware-clock sync.
static int64	cmlabs::NetTimeAdjust = 0
	Signed network time adjustment (µs) applied when slaved to a remote master.

Detailed Description

CMSDK time: µs-resolution 64-bit timestamps and the Time Mapping Constant (TMC).

All Psyclone timestamps are unsigned 64-bit integers counting microseconds since year 0000 (proleptic Gregorian); the constant USEC_YEAR_0_TO_1970 is the offset of the Unix epoch in this scheme, so unix_us = psytime - USEC_YEAR_0_TO_1970. A uint64 of µs-since-year-0 does not overflow for ~584,000 years, so wrap-around of timestamps themselves is not a practical concern; EstNextTMCWrap() instead estimates the wrap of the underlying hardware counter.

The TMC (Time Mapping Constant) maps the machine's monotonic hardware clock to this absolute timescale: GetTimeNow() = monotonic_reading + CurrentTMC (+ NetTimeAdjust when slaved to a remote master). SyncToHardwareClock() recomputes the TMC from the wall clock; slave nodes adjust via SetCurrentNetSyncDif() so that all nodes in a distributed system share one timeline. Platform note: on Windows the monotonic source is QueryPerformanceCounter/Frequency; on POSIX (Linux/macOS) it is clock_gettime(CLOCK_MONOTONIC) paired with gettimeofday() for the wall-clock anchor.

Definition in file PsyTime.h.