PsyTime.cpp File Reference

Implementation of the CMSDK time functions (see PsyTime.h). More...

#include "PsyTime.h"
#include "Utils.h"
#include "UnitTestFramework.h"

Include dependency graph for PsyTime.cpp:

Go to the source code of this file.

Namespaces
namespace	cmlabs

Functions
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::GetTimeNow ()
	Return the current absolute time (µs since year 0) according to the TMC.
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::SyncToHardwareClock ()
	Recompute the Time Mapping Constant by anchoring the monotonic clock to the wall clock.
uint64	cmlabs::EstNextTMCWrap ()
	Estimate when the underlying hardware counter will next wrap around.
struct PsyDateAndTime	cmlabs::GetDateAndTimeUTC (uint64 t)
	Break a timestamp into calendar fields in UTC.
struct PsyDateAndTime	cmlabs::GetDateAndTime (uint64 t, bool local=true)
	Break a timestamp into calendar fields.
uint64	cmlabs::GetTimeFromPsyDateAndTime (struct PsyDateAndTime &tad)
	Convert a broken-down PsyDateAndTime back into a µs timestamp.
struct PsyDateAndTime	cmlabs::GetTimeDifference (uint64 t1, uint64 t2)
	Express the difference t1 - t2 as calendar fields (negative flag set when t2 > t1).
uint32	cmlabs::GetTimeOffsetGMT ()
struct PsyDateAndTime	cmlabs::GetTimeDifference (int64 dif)
	Express a signed µs difference as calendar fields.
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::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.
void	cmlabs::Register_PsyTime_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::PrintDate (uint64 t, bool local=true)
	Date only, human-readable.
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.
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::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".
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::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::PrintTimeDifString (uint64 t, bool us=true, bool ms=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.

Detailed Description

Implementation of the CMSDK time functions (see PsyTime.h).

Platform notes: the monotonic time source is QueryPerformanceCounter/ QueryPerformanceFrequency on Windows (_WIN32) and clock_gettime(CLOCK_MONOTONIC) on POSIX (Linux/macOS); SyncToHardwareClock() anchors it to the wall clock (GetSystemTime / gettimeofday) by waiting for a tick edge, producing the Time Mapping Constant used by GetTimeNow().

Definition in file PsyTime.cpp.