Time » CnxClock module

The CnxClock module provides types and functions for working with system, local, and global clocks. It provides functionality similar to C++'s std::chrono clocks and makes cross-platform time-related operations simple and straight forward. Access to and functionality of the realtime system clock, a high-resolution monotonic clock, a realtime UTC clock, and realtime local time clock are all provided.

The system clock (cnx_system_clock) and related functions always operate in local machine time, operating relative to the UNIX epoch. On Windows, machine time is traditionally in local time. On other platforms, it is usually in UTC.

The steady clock (or monotonic clock, cnx_steady_clock) is a high-resolution monotonic clock suitable for performance, timing, metrics, etc. It is only available if a monotonic clock is available and supported on the being-compiled-for platform (CNX_NO_MONOTONIC_CLOCK must be false).

The generic high resolution clock (cnx_high_resolution_clock) is the highest resolution clock available and supported on the system. If cnx_steady_clock is available, cnx_high_resolution_clock will be equivalent to it. Otherwise, it will be cnx_system_clock. cnx_high_resolution_clock is provided for convenience, but because of the uncertainty of what clock it will actually be if perfectly accurate timing is necessary, it is preferred to check for cnx_steady_clock availability explicitly.

The UTC clock (cnx_utc_clock) and related functions operate in UTC mean time, operating relative to the UNIX epoch.

The local time clock (cnx_local_clock) and related functions operate in local timezone time, operating relative to the UNIX epoch.

Example:

#include <Cnx/time/Clock.h>
#include <Cnx/IO.h>

// print the local time formatted in ISO 8601 format (YYYY-MM-DD|H:M:S+-hh:mm))
void local_time_example(void) {
    let current_time = cnx_clock_now(&cnx_local_clock);
    println("{}", as_format_t(CnxTimePoint, current_time));
}

// time a function call and print the duration in debug format
void time_to_call_example(void) {
    // `cnx_steady_clock` is only available if a monotonic clock is available
    #if CNX_NO_MONOTONIC_CLOCK
        let timer_clock_ptr = &cnx_system_clock;
    #else
        let timer_clock_ptr = &cnx_steady_clock;
    #endif
    // at this point, `timer_clock_ptr` is equivalent to `&cnx_high_resolution_clock`.
    // On platforms when one is available, `cnx_high_resolution_clock` will be the monotonic
    // `cnx_steady_clock`, otherwise it will be `cnx_system_clock`
    let start_time = cnx_clock_now(timer_clock_ptr);
    local_time_example();
    let end_time = cnx_clock_now(timer_clock_ptr);
    let difference = cnx_time_point_subtract(end_time, start_time).time_since_epoch;
    println("Took {D} to call local_time_example()", difference);
}

// print the current UTC time formatted in ISO 8601 format (YYYY-MM-DD|H:M:S+-hh:mm))
void utc_time_example(void) {
    let current_utc_time = cnx_clock_now(&cnx_utc_clock);
    println("{}", as_format_t(CnxTimePoint, current_utc_time));
}

// print the current system time formatted in ISO 8601 format (YYYY-MM-DD|H:M:S+-hh:mm))
// (This should be local time on Windows, UTC time on others)
void system_time_example(void) {
    let current_system_time = cnx_clock_now(&cnx_system_clock);
    println("{}", as_format_t(CnxTimePoint, current_system_time));
}

Classes

struct CnxClock
The CnxClock trait defines the interface that must be implemented by any Cnx-compatible clock. It intentionally mirrors the API of C++'s standard clock types, along with some additional functionality.

Enums

enum CnxClockResolution { CNX_CLOCK_NANOSECONDS, CNX_CLOCK_MICROSECONDS, CNX_CLOCK_MILLISECONDS, CNX_CLOCK_SECONDS }
CnxClockResolution lists the valid resolutions for CnxClock compatible clocks

Typedefs

using CnxClockResolution = enum CnxClockResolution
CnxClockResolution lists the valid resolutions for CnxClock compatible clocks

Functions

CnxTimePoint cnx_clock_now(const CnxClock*restrict self)
Returns a CnxTimePoint corresponding to the current time on the given clock.
CnxTimePoint cnx_clock_min_time_point(const CnxClock*restrict self)
Returns the minimum possible CnxTimePoint able to be associated with the given clock.
CnxTimePoint cnx_clock_max_time_point(const CnxClock*restrict self)
Returns the maximum possible CnxTimePoint able to be associated with the given clock.
CnxClockResolution cnx_clock_resolution(const CnxClock*restrict self)
Returns the resolution of the given clock.
CnxRatio cnx_clock_resolution_as_ratio(const CnxClock*restrict self)
Returns the resolution of the given clock.
CnxTimePointLocale cnx_clock_locale(const CnxClock*restrict self)
Returns the locale associated with the given clock.
CnxString cnx_clock_format(const CnxFormat*restrict self, CnxFormatContext context)
Implements the allocator un-aware portion of the CnxFormat trait for all CnxClocks.
CnxString cnx_clock_format_with_allocator(const CnxFormat*restrict self, CnxFormatContext context, CnxAllocator allocator)
Implements the allocator aware portion of the CnxFormat trait for all CnxClocks.
static ImplTraitFor(CnxFormat, CnxClock, cnx_clock_is_specifier_valid, cnx_clock_format, cnx_clock_format_with_allocator)
Implements the CnxFormat trait for CnxClock
CnxTimePoint cnx_system_clock_now(void)
Returns a CnxTimePoint corresponding to the current time on the system clock.
CnxTimePoint cnx_system_clock_min_time_point(void)
Returns the minimum possible CnxTimePoint able to be associated with the system clock.
CnxTimePoint cnx_system_clock_max_time_point(void)
Returns the maximum possible CnxTimePoint able to be associated with the system clock.
CnxClockResolution cnx_system_clock_resolution(void)
Returns the resolution of the system clock.
CnxRatio cnx_system_clock_resolution_as_ratio(void)
Returns the resolution of the system clock.
CnxTimePointLocale cnx_system_clock_locale(void)
Returns the locale of the system clock.
CnxTimePoint cnx_steady_clock_now(void)
Returns a CnxTimePoint corresponding to the current time on the steady clock.
CnxTimePoint cnx_steady_clock_min_time_point(void)
Returns the minimum possible CnxTimePoint able to be associated with the steady clock.
CnxTimePoint cnx_steady_clock_max_time_point(void)
Returns the maximum possible CnxTimePoint able to be associated with the steady clock.
CnxClockResolution cnx_steady_clock_resolution(void)
Returns the resolution of the steady clock.
CnxRatio cnx_steady_clock_resolution_as_ratio(void)
Returns the resolution of the steady clock.
CnxTimePointLocale cnx_steady_clock_locale(void)
Returns the locale of the steady clock.
CnxTimePoint cnx_high_resolution_clock_now(void)
Returns a CnxTimePoint corresponding to the current time on the high resolution clock.
CnxTimePoint cnx_high_resolution_clock_min_time_point(void)
Returns the minimum possible CnxTimePoint able to be associated with the high resolution clock.
CnxTimePoint cnx_high_resolution_clock_max_time_point(void)
Returns the maximum possible CnxTimePoint able to be associated with the high resolution clock.
CnxClockResolution cnx_high_resolution_clock_resolution(void)
Returns the resolution of the high resolution clock.
CnxRatio cnx_high_resolution_clock_resolution_as_ratio(void)
Returns the resolution of the high resolution clock.
CnxTimePointLocale cnx_high_resolution_clock_locale(void)
Returns the locale of the high resolution clock.
CnxTimePoint cnx_utc_clock_now(void)
Returns a CnxTimePoint corresponding to the current time on the UTC clock.
CnxTimePoint cnx_utc_clock_min_time_point(void)
Returns the minimum possible CnxTimePoint able to be associated with the UTC clock.
CnxTimePoint cnx_utc_clock_max_time_point(void)
Returns the maximum possible CnxTimePoint able to be associated with the UTC clock.
CnxClockResolution cnx_utc_clock_resolution(void)
Returns the resolution of the UTC clock.
CnxRatio cnx_utc_clock_resolution_as_ratio(void)
Returns the resolution of the UTC clock.
CnxTimePointLocale cnx_utc_clock_locale(void)
Returns the locale of the UTC clock.
CnxTimePoint cnx_local_clock_now(void)
Returns a CnxTimePoint corresponding to the current time on the local clock.
CnxTimePoint cnx_local_clock_min_time_point(void)
Returns the minimum possible CnxTimePoint able to be associated with the local clock.
CnxTimePoint cnx_local_clock_max_time_point(void)
Returns the maximum possible CnxTimePoint able to be associated with the local clock.
CnxClockResolution cnx_local_clock_resolution(void)
Returns the resolution of the local clock.
CnxRatio cnx_local_clock_resolution_as_ratio(void)
Returns the resolution of the local clock.
CnxTimePointLocale cnx_local_clock_locale(void)
Returns the locale of the local clock.
CnxTimePoint cnx_convert_utc_to_local_time(CnxTimePoint utc)
Converts the given CnxTimePoint in UTC time to a CnxTimePoint in local time.
CnxTimePoint cnx_convert_local_time_to_utc(CnxTimePoint local_time)
Converts the given CnxTimePoint in local time to a CnxTimePoint in UTC time.

Variables

static let cnx_system_clock
The system clock.
static let cnx_steady_clock
The monotonic clock.
static let cnx_high_resolution_clock
The high resolution clock This will be equivalent to cnx_system_clock if CNX_NO_MONOTONIC_CLOCK is true (in which case a monotonic clock is not supported on the being-compiled-for platform). Otherwise, it will be a monotonic clock equivalent to cnx_steady_clock
static let cnx_utc_clock
The UTC clock.
static let cnx_local_clock
The local time clock.

Defines

#define CNX_NO_MONOTONIC_CLOCK
If CNX_NO_MONOTONIC_CLOCK is true, then either Cnx doesn't support a monotonic clock on the being-compiled-for-platform, the being-compiled-for platform itself doesn't, or both, and cnx_steady_clock and related functions are not available.

Enum documentation

enum CnxClockResolution
#include <include/Cnx/time/Clock.h>

CnxClockResolution lists the valid resolutions for CnxClock compatible clocks

Typedef documentation

typedef enum CnxClockResolution CnxClockResolution
#include <include/Cnx/time/Clock.h>

CnxClockResolution lists the valid resolutions for CnxClock compatible clocks

Function documentation

CnxTimePoint cnx_clock_now(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the given clock.

Parameters
self - The CnxClock to retrieve the current time from
Returns The current time on self

CnxTimePoint cnx_clock_min_time_point(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the given clock.

Parameters
self - The CnxClock to get the minimum possible associatable CnxTimePoint of
Returns The minimum CnxTimePoint associatable with self

CnxTimePoint cnx_clock_max_time_point(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the given clock.

Parameters
self - The CnxClock to get the maximum possible associatable CnxTimePoint of
Returns The minimum CnxTimePoint associatable with self

CnxClockResolution cnx_clock_resolution(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the given clock.

Parameters
self - The CnxClock to get the resolution of
Returns The resolution of self as a CnxClockResolution

CnxRatio cnx_clock_resolution_as_ratio(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the given clock.

Parameters
self - The CnxClock to get the resolution of
Returns The resolution of self as a CnxRatio relative to seconds

CnxTimePointLocale cnx_clock_locale(const CnxClock*restrict self)
#include <include/Cnx/time/Clock.h>

Returns the locale associated with the given clock.

Parameters
self - The CnxClock to get the locale of
Returns The locale of self

CnxString cnx_clock_format(const CnxFormat*restrict self, CnxFormatContext context)
#include <include/Cnx/time/Clock.h>

Implements the allocator un-aware portion of the CnxFormat trait for all CnxClocks.

Parameters
self - The CnxFormat implementor to get the text representation of
context - The CnxFormatContext specifying how formatting should be done
Returns The text representation of self as a CnxString

CnxString cnx_clock_format_with_allocator(const CnxFormat*restrict self, CnxFormatContext context, CnxAllocator allocator)
#include <include/Cnx/time/Clock.h>

Implements the allocator aware portion of the CnxFormat trait for all CnxClocks.

Parameters
self - The CnxFormat implementor to get the text representation of
context - The CnxFormatContext specifying how formatting should be done
allocator - The CnxAllocator to use for any necessary memory allocation
Returns The text representation of self as a CnxString

CnxTimePoint cnx_system_clock_now(void)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the system clock.

Returns The current time on the system clock

CnxTimePoint cnx_system_clock_min_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the system clock.

Returns The minimum CnxTimePoint associatable with the system clock

CnxTimePoint cnx_system_clock_max_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the system clock.

Returns The maximum CnxTimePoint associatable with the system clock

CnxClockResolution cnx_system_clock_resolution(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the system clock.

Returns The resolution of the system clock as a CnxClockResolution

CnxRatio cnx_system_clock_resolution_as_ratio(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the system clock.

Returns The resolution of the system clock as a CnxRatio relative to seconds

CnxTimePointLocale cnx_system_clock_locale(void)
#include <include/Cnx/time/Clock.h>

Returns the locale of the system clock.

Returns The locale of the system clock

CnxTimePoint cnx_steady_clock_now(void)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the steady clock.

Returns The current time on the steady clock

CnxTimePoint cnx_steady_clock_min_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the steady clock.

Returns The minimum CnxTimePoint associatable with the steady clock

CnxTimePoint cnx_steady_clock_max_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the steady clock.

Returns The maximum CnxTimePoint associatable with the steady clock

CnxClockResolution cnx_steady_clock_resolution(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the steady clock.

Returns The resolution of the steady clock as a CnxClockResolution

CnxRatio cnx_steady_clock_resolution_as_ratio(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the steady clock.

Returns The resolution of the steady clock as a CnxRatio relative to seconds

CnxTimePointLocale cnx_steady_clock_locale(void)
#include <include/Cnx/time/Clock.h>

Returns the locale of the steady clock.

Returns The locale of the steady clock

CnxTimePoint cnx_high_resolution_clock_now(void)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the high resolution clock.

Returns The current time on the high resolution clock

CnxTimePoint cnx_high_resolution_clock_min_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the high resolution clock.

Returns The minimum CnxTimePoint associatable with the high resolution clock

CnxTimePoint cnx_high_resolution_clock_max_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the high resolution clock.

Returns The maximum CnxTimePoint associatable with the high resolution clock

CnxClockResolution cnx_high_resolution_clock_resolution(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the high resolution clock.

Returns The resolution of the high resolution clock as a CnxClockResolution

CnxRatio cnx_high_resolution_clock_resolution_as_ratio(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the high resolution clock.

Returns The resolution of the high resolution clock as a CnxRatio relative to seconds

CnxTimePointLocale cnx_high_resolution_clock_locale(void)
#include <include/Cnx/time/Clock.h>

Returns the locale of the high resolution clock.

Returns The locale of the high resolution clock

CnxTimePoint cnx_utc_clock_now(void)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the UTC clock.

Returns The current time on the UTC clock

CnxTimePoint cnx_utc_clock_min_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the UTC clock.

Returns The minimum CnxTimePoint associatable with the UTC clock

CnxTimePoint cnx_utc_clock_max_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the UTC clock.

Returns The maximum CnxTimePoint associatable with the UTC clock

CnxClockResolution cnx_utc_clock_resolution(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the UTC clock.

Returns The resolution of the UTC clock as a CnxClockResolution

CnxRatio cnx_utc_clock_resolution_as_ratio(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the UTC clock.

Returns The resolution of the UTC clock as a CnxRatio relative to seconds

CnxTimePointLocale cnx_utc_clock_locale(void)
#include <include/Cnx/time/Clock.h>

Returns the locale of the UTC clock.

Returns The locale of the UTC clock

CnxTimePoint cnx_local_clock_now(void)
#include <include/Cnx/time/Clock.h>

Returns a CnxTimePoint corresponding to the current time on the local clock.

Returns The current time on the local clock

CnxTimePoint cnx_local_clock_min_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the minimum possible CnxTimePoint able to be associated with the local clock.

Returns The minimum CnxTimePoint associatable with the local clock

CnxTimePoint cnx_local_clock_max_time_point(void)
#include <include/Cnx/time/Clock.h>

Returns the maximum possible CnxTimePoint able to be associated with the local clock.

Returns The maximum CnxTimePoint associatable with the local clock

CnxClockResolution cnx_local_clock_resolution(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the local clock.

Returns The resolution of the local clock as a CnxClockResolution

CnxRatio cnx_local_clock_resolution_as_ratio(void)
#include <include/Cnx/time/Clock.h>

Returns the resolution of the local clock.

Returns The resolution of the local clock as a CnxRatio relative to seconds

CnxTimePointLocale cnx_local_clock_locale(void)
#include <include/Cnx/time/Clock.h>

Returns the locale of the local clock.

Returns The locale of the local clock

CnxTimePoint cnx_convert_utc_to_local_time(CnxTimePoint utc)
#include <include/Cnx/time/Clock.h>

Converts the given CnxTimePoint in UTC time to a CnxTimePoint in local time.

Parameters
utc - The time point to convert to local time
Returns utc converted to local time

CnxTimePoint cnx_convert_local_time_to_utc(CnxTimePoint local_time)
#include <include/Cnx/time/Clock.h>

Converts the given CnxTimePoint in local time to a CnxTimePoint in UTC time.

Parameters
local_time - The time point to convert to UTC time
Returns local_time converted to UTC time

Variable documentation

static let cnx_system_clock
#include <include/Cnx/time/Clock.h>

The system clock.

static let cnx_steady_clock
#include <include/Cnx/time/Clock.h>

The monotonic clock.

static let cnx_high_resolution_clock
#include <include/Cnx/time/Clock.h>

The high resolution clock This will be equivalent to cnx_system_clock if CNX_NO_MONOTONIC_CLOCK is true (in which case a monotonic clock is not supported on the being-compiled-for platform). Otherwise, it will be a monotonic clock equivalent to cnx_steady_clock

static let cnx_utc_clock
#include <include/Cnx/time/Clock.h>

The UTC clock.

static let cnx_local_clock
#include <include/Cnx/time/Clock.h>

The local time clock.

Define documentation

#define CNX_NO_MONOTONIC_CLOCK
#include <include/Cnx/time/Clock.h>

If CNX_NO_MONOTONIC_CLOCK is true, then either Cnx doesn't support a monotonic clock on the being-compiled-for-platform, the being-compiled-for platform itself doesn't, or both, and cnx_steady_clock and related functions are not available.