View source code
Display the source code in core/time.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Enum core.time.ClockType

What type of clock to use with MonoTime / MonoTimeImpl or std.datetime.Clock.currTime. They default to ClockType.normal, and most programs do not need to ever deal with the others.

enum ClockType : int { ... }

The other ClockTypes are provided so that other clocks provided by the underlying C, system calls can be used with MonoTimeImpl or std.datetime.Clock.currTime without having to use the C API directly.

In the case of the monotonic time, MonoTimeImpl is templatized on ClockType, whereas with std.datetime.Clock.currTime, its a runtime argument, since in the case of the monotonic time, the type of the clock affects the resolution of a MonoTimeImpl object, whereas with std.datetime.SysTime, its resolution is always hecto-nanoseconds regardless of the source of the time.

ClockType.normal, ClockType.coarse, and ClockType.precise work with both Clock.currTime and MonoTimeImpl. ClockType.second only works with Clock.currTime. The others only work with MonoTimeImpl.

Enum members

NameDescription
bootTime Linux,OpenBSD-Only

Uses CLOCK_BOOTTIME.

coarse Use the coarse clock, not the normal one (e.g. on Linux, that would be CLOCK_REALTIME_COARSE instead of CLOCK_REALTIME for clock_gettime if a function is using the realtime clock). It's generally faster to get the time with the coarse clock than the normal clock, but it's less precise (e.g. 1 msec instead of 1 usec or 1 nsec). Howeover, it is guaranteed to still have sub-second precision (just not as high as with ClockType.normal).

On systems which do not support a coarser clock, MonoTimeImpl!(ClockType.coarse) will internally use the same clock as MonoTime does, and Clock.currTime!(ClockType.coarse) will use the same clock as Clock.currTime. This is because the coarse clock is doing the same thing as the normal clock (just at lower precision), whereas some of the other clock types (e.g. ClockType.processCPUTime) mean something fundamentally different. So, treating those as ClockType.normal on systems where they weren't natively supported would give misleading results.

Most programs should not use the coarse clock, exactly because it's less precise, and most programs don't need to get the time often enough to care, but for those rare programs that need to get the time extremely frequently (e.g. hundreds of thousands of times a second) but don't care about high precision, the coarse clock might be appropriate.

Currently, only Linux and FreeBSD/DragonFlyBSD support a coarser clock, and on other platforms, it's treated as ClockType.normal.

normal Use the normal clock.
precise Uses a more precise clock than the normal one (which is already very precise), but it takes longer to get the time. Similarly to ClockType.coarse, if it's used on a system that does not support a more precise clock than the normal one, it's treated as equivalent to ClockType.normal.

Currently, only FreeBSD/DragonFlyBSD supports a more precise clock, where it uses CLOCK_MONOTONIC_PRECISE for the monotonic time and CLOCK_REALTIME_PRECISE for the wall clock time.

processCPUTime Linux,OpenBSD,Solaris-Only

Uses CLOCK_PROCESS_CPUTIME_ID.

raw Linux-Only

Uses CLOCK_MONOTONIC_RAW.

second Uses a clock that has a precision of one second (contrast to the coarse clock, which has sub-second precision like the normal clock does).

FreeBSD/DragonFlyBSD are the only systems which specifically have a clock set up for this (it has CLOCK_SECOND to use with clock_gettime which takes advantage of an in-kernel cached value), but on other systems, the fastest function available will be used, and the resulting SysTime will be rounded down to the second if the clock that was used gave the time at a more precise resolution. So, it's guaranteed that the time will be given at a precision of one second and it's likely the case that will be faster than ClockType.normal, since there tend to be several options on a system to get the time at low resolutions, and they tend to be faster than getting the time at high resolutions.

So, the primary difference between ClockType.coarse and ClockType.second is that ClockType.coarse sacrifices some precision in order to get speed but is still fairly precise, whereas ClockType.second tries to be as fast as possible at the expense of all sub-second precision.

threadCPUTime Linux,OpenBSD,Solaris-Only

Uses CLOCK_THREAD_CPUTIME_ID.

uptime DragonFlyBSD,FreeBSD,OpenBSD-Only

Uses CLOCK_UPTIME.

uptimeCoarse FreeBSD-Only

Uses CLOCK_UPTIME_FAST.

uptimePrecise FreeBSD-Only

Uses CLOCK_UPTIME_PRECISE.

Authors

Jonathan M Davis and Kato Shoichi

License

Boost License 1.0.